@rei-standard/amsg-shared 0.4.0-next.1 → 0.4.0-next.2

package/dist/index.mjs

@@ -1,3 +1,485 @@
+// src/webcrypto-utils.js
+var TEXT_ENCODER = new TextEncoder();
+var TEXT_DECODER = new TextDecoder("utf-8", { fatal: false });
+function toUint8(buf) {
+  if (buf instanceof Uint8Array) return buf;
+  if (buf instanceof ArrayBuffer) return new Uint8Array(buf);
+  if (ArrayBuffer.isView(buf)) return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  throw new TypeError("Expected ArrayBuffer / Uint8Array");
+}
+function concatBytes(...chunks) {
+  let total = 0;
+  for (const c of chunks) total += c.byteLength;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c instanceof Uint8Array ? c : new Uint8Array(c.buffer || c), offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+function utf8(str) {
+  return TEXT_ENCODER.encode(String(str));
+}
+function utf8Decode(buf) {
+  return TEXT_DECODER.decode(toUint8(buf));
+}
+function bytesToBase64(buf) {
+  const bytes = toUint8(buf);
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) {
+    bin += String.fromCharCode(bytes[i]);
+  }
+  return typeof btoa === "function" ? btoa(bin) : Buffer.from(bin, "binary").toString("base64");
+}
+function bytesToBase64Url(buf) {
+  return bytesToBase64(buf).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64UrlToBytes(input) {
+  const s = String(input).replace(/-/g, "+").replace(/_/g, "/");
+  const pad = (4 - s.length % 4) % 4;
+  const padded = s + "=".repeat(pad);
+  const bin = typeof atob === "function" ? atob(padded) : Buffer.from(padded, "base64").toString("binary");
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function jsonToBase64Url(value) {
+  return bytesToBase64Url(utf8(JSON.stringify(value)));
+}
+function bytesToHex(buf) {
+  const bytes = toUint8(buf);
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    out += bytes[i].toString(16).padStart(2, "0");
+  }
+  return out;
+}
+function hexToBytes(hex) {
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+async function hmacSha256(keyBytes, data) {
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    toUint8(keyBytes),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await globalThis.crypto.subtle.sign("HMAC", key, toUint8(data));
+  return new Uint8Array(sig);
+}
+function timingSafeEqualBytes(a, b) {
+  const x = toUint8(a);
+  const y = toUint8(b);
+  if (x.length !== y.length) return false;
+  let diff = 0;
+  for (let i = 0; i < x.length; i++) {
+    diff |= x[i] ^ y[i];
+  }
+  return diff === 0;
+}
+function randomBytes(n) {
+  const out = new Uint8Array(n);
+  globalThis.crypto.getRandomValues(out);
+  return out;
+}
+function randomUUID() {
+  return globalThis.crypto.randomUUID();
+}
+
+// src/llm-messages.js
+var VALID_LLM_MESSAGE_ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant", "tool"]);
+var LLM_MESSAGES_ERROR = Object.freeze({
+  MESSAGES_NOT_ARRAY: "MESSAGES_NOT_ARRAY",
+  MESSAGE_NOT_OBJECT: "MESSAGE_NOT_OBJECT",
+  INVALID_ROLE: "INVALID_ROLE",
+  TOOL_CALL_MALFORMED: "TOOL_CALL_MALFORMED",
+  TOOL_CONTENT_INVALID: "TOOL_CONTENT_INVALID",
+  TOOL_CALL_ID_MISSING: "TOOL_CALL_ID_MISSING",
+  CONTENT_EMPTY_STRING: "CONTENT_EMPTY_STRING",
+  CONTENT_EMPTY_ARRAY: "CONTENT_EMPTY_ARRAY",
+  CONTENT_INVALID_TYPE: "CONTENT_INVALID_TYPE"
+});
+function validateLlmMessagesShape(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return { code: LLM_MESSAGES_ERROR.MESSAGES_NOT_ARRAY };
+  }
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (!m || typeof m !== "object" || Array.isArray(m)) {
+      return { code: LLM_MESSAGES_ERROR.MESSAGE_NOT_OBJECT, index: i };
+    }
+    if (!VALID_LLM_MESSAGE_ROLES.has(m.role)) {
+      return { code: LLM_MESSAGES_ERROR.INVALID_ROLE, index: i };
+    }
+    const isAssistantToolCallCarrier = m.role === "assistant" && Array.isArray(m.tool_calls) && m.tool_calls.length > 0;
+    if (isAssistantToolCallCarrier) {
+      for (let j = 0; j < m.tool_calls.length; j++) {
+        const tc = m.tool_calls[j];
+        if (!tc || typeof tc !== "object" || typeof tc.id !== "string" || !tc.function) {
+          return { code: LLM_MESSAGES_ERROR.TOOL_CALL_MALFORMED, index: i, toolCallIndex: j };
+        }
+      }
+      continue;
+    }
+    if (m.role === "tool") {
+      if (typeof m.content !== "string" && !Array.isArray(m.content)) {
+        return { code: LLM_MESSAGES_ERROR.TOOL_CONTENT_INVALID, index: i };
+      }
+      if (typeof m.tool_call_id !== "string" || !m.tool_call_id) {
+        return { code: LLM_MESSAGES_ERROR.TOOL_CALL_ID_MISSING, index: i };
+      }
+      continue;
+    }
+    if (typeof m.content === "string") {
+      if (!m.content) {
+        return { code: LLM_MESSAGES_ERROR.CONTENT_EMPTY_STRING, index: i };
+      }
+    } else if (Array.isArray(m.content)) {
+      if (m.content.length === 0) {
+        return { code: LLM_MESSAGES_ERROR.CONTENT_EMPTY_ARRAY, index: i };
+      }
+    } else {
+      return { code: LLM_MESSAGES_ERROR.CONTENT_INVALID_TYPE, index: i };
+    }
+  }
+  return null;
+}
+
+// src/llm-call.js
+async function callLlm(payload, options = {}) {
+  const requireContent = options.requireContent !== false;
+  const timeoutMs = typeof options.timeoutMs === "number" && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 3e5;
+  const fetchImpl = options.fetch || globalThis.fetch;
+  const normalizedApiUrl = normalizeAiApiUrl(payload.apiUrl);
+  const requestBody = buildLlmRequestBody(payload, options);
+  const aiResponse = await fetchImpl(normalizedApiUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${payload.apiKey}`
+    },
+    body: JSON.stringify(requestBody),
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+  if (!aiResponse.ok) {
+    if (aiResponse.status === 405) {
+      throw new Error(
+        `AI API error: 405 Method Not Allowed. apiUrl must point to a full chat endpoint (for example: /chat/completions). Received: ${normalizedApiUrl}`
+      );
+    }
+    throw new Error(
+      `AI API error: ${aiResponse.status} ${aiResponse.statusText || "Unknown Error"}. Request URL: ${normalizedApiUrl}`
+    );
+  }
+  const aiData = await aiResponse.json();
+  const rawContent = aiData?.choices?.[0]?.message?.content;
+  if (requireContent && (typeof rawContent !== "string" || !rawContent.trim())) {
+    throw new Error("AI API error: response missing choices[0].message.content");
+  }
+  return { response: aiData, content: typeof rawContent === "string" ? rawContent.trim() : "" };
+}
+function buildLlmRequestBody(payload, options = {}) {
+  const llmMessages = Array.isArray(payload.messages) && payload.messages.length > 0 ? payload.messages : [{ role: "user", content: payload.completePrompt }];
+  const requestBody = {
+    model: payload.primaryModel,
+    messages: llmMessages
+  };
+  if (options.stream !== void 0) {
+    requestBody.stream = options.stream;
+  }
+  if (payload.temperature !== void 0 && payload.temperature !== null) {
+    requestBody.temperature = payload.temperature;
+  } else if (!Array.isArray(payload.messages)) {
+    requestBody.temperature = 0.8;
+  }
+  if (options.forwardTools !== false && Array.isArray(payload.tools) && payload.tools.length > 0) {
+    requestBody.tools = payload.tools;
+    if (payload.toolChoice !== void 0 && payload.toolChoice !== null) {
+      requestBody.tool_choice = payload.toolChoice;
+    }
+  }
+  if (payload.maxTokens === void 0 || payload.maxTokens === null) {
+    return requestBody;
+  }
+  if (!Number.isInteger(payload.maxTokens) || payload.maxTokens <= 0) {
+    throw new Error("Invalid maxTokens: maxTokens must be a positive integer when provided.");
+  }
+  requestBody.max_tokens = payload.maxTokens;
+  return requestBody;
+}
+function normalizeAiApiUrl(apiUrl) {
+  const trimmed = String(apiUrl || "").trim();
+  if (!trimmed) {
+    throw new Error(
+      "Invalid apiUrl: apiUrl is required. Please provide a chat endpoint URL (for example: https://api.openai.com or https://api.openai.com/v1/chat/completions)."
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(
+      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
+    );
+  }
+  let path = parsed.pathname.replace(/\/+$/, "") || "/";
+  if (/\/chat\/completions$/.test(path)) {
+  } else if (path === "/") {
+    path = "/v1/chat/completions";
+  } else if (/\/v\d+$/.test(path)) {
+    path = `${path}/chat/completions`;
+  }
+  parsed.pathname = path;
+  return parsed.toString();
+}
+
+// src/webpush.js
+var KEY_INFO_PREFIX = utf8("WebPush: info\0");
+var CEK_INFO = utf8("Content-Encoding: aes128gcm\0");
+var NONCE_INFO = utf8("Content-Encoding: nonce\0");
+var VAPID_DEFAULT_TTL = 60;
+var VAPID_TOKEN_LIFETIME = 12 * 3600;
+var RECORD_SIZE = 4096;
+async function sendWebPush({ subscription, payload, vapid, ttl, fetch: fetchImpl }) {
+  if (!subscription || typeof subscription.endpoint !== "string") {
+    throw new Error("sendWebPush: invalid subscription");
+  }
+  if (typeof payload !== "string") {
+    throw new Error("sendWebPush: payload must be a string");
+  }
+  if (!vapid || !vapid.email || !vapid.publicKey || !vapid.privateKey) {
+    throw new Error("VAPID_CONFIG_MISSING");
+  }
+  const subscriptionKeys = subscription.keys || {};
+  if (typeof subscriptionKeys.p256dh !== "string" || typeof subscriptionKeys.auth !== "string") {
+    throw new Error("sendWebPush: subscription.keys.p256dh and .auth are required");
+  }
+  const encryptedBody = await encryptPushPayload({
+    plaintext: utf8(payload),
+    uaPublicKey: base64UrlToBytes(subscriptionKeys.p256dh),
+    authSecret: base64UrlToBytes(subscriptionKeys.auth)
+  });
+  const jwt = await buildVapidJwt({
+    audience: originOf(subscription.endpoint),
+    subject: normalizeVapidSubject(vapid.email),
+    publicKey: vapid.publicKey,
+    privateKey: vapid.privateKey
+  });
+  const fetchFn = fetchImpl || globalThis.fetch;
+  if (typeof fetchFn !== "function") {
+    throw new Error("sendWebPush: no fetch implementation available");
+  }
+  const res = await fetchFn(subscription.endpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/octet-stream",
+      "Content-Encoding": "aes128gcm",
+      "TTL": String(Number.isFinite(ttl) ? ttl : VAPID_DEFAULT_TTL),
+      "Authorization": `vapid t=${jwt}, k=${vapid.publicKey}`
+    },
+    body: encryptedBody
+  });
+  if (!res.ok) {
+    const text = await safeReadText(res);
+    const err = new Error(
+      `Web Push delivery failed: ${res.status} ${res.statusText || ""}${text ? ` \u2014 ${text}` : ""}`
+    );
+    err.code = "PUSH_SEND_FAILED";
+    err.statusCode = res.status;
+    throw err;
+  }
+  return {
+    statusCode: res.status,
+    body: await safeReadText(res),
+    headers: res.headers
+  };
+}
+async function encryptPushPayload({ plaintext, uaPublicKey, authSecret }) {
+  const asKeyPair = await globalThis.crypto.subtle.generateKey(
+    { name: "ECDH", namedCurve: "P-256" },
+    true,
+    ["deriveBits"]
+  );
+  const asPublicRaw = new Uint8Array(
+    await globalThis.crypto.subtle.exportKey("raw", asKeyPair.publicKey)
+  );
+  const uaPublicCryptoKey = await globalThis.crypto.subtle.importKey(
+    "raw",
+    uaPublicKey,
+    { name: "ECDH", namedCurve: "P-256" },
+    false,
+    []
+  );
+  const ecdhSecret = new Uint8Array(
+    await globalThis.crypto.subtle.deriveBits(
+      { name: "ECDH", public: uaPublicCryptoKey },
+      asKeyPair.privateKey,
+      256
+    )
+  );
+  const keyInfo = concatBytes(KEY_INFO_PREFIX, uaPublicKey, asPublicRaw);
+  const ikm = await hkdfSha256(authSecret, ecdhSecret, keyInfo, 32);
+  const salt = randomBytes(16);
+  const cekBytes = await hkdfSha256(salt, ikm, CEK_INFO, 16);
+  const cek = await globalThis.crypto.subtle.importKey(
+    "raw",
+    cekBytes,
+    { name: "AES-GCM" },
+    false,
+    ["encrypt"]
+  );
+  const nonce = await hkdfSha256(salt, ikm, NONCE_INFO, 12);
+  const padded = concatBytes(plaintext, new Uint8Array([2]));
+  const ciphertext = new Uint8Array(
+    await globalThis.crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce }, cek, padded)
+  );
+  const header = new Uint8Array(16 + 4 + 1 + asPublicRaw.byteLength);
+  header.set(salt, 0);
+  writeUint32BE(header, 16, RECORD_SIZE);
+  header[20] = asPublicRaw.byteLength;
+  header.set(asPublicRaw, 21);
+  return concatBytes(header, ciphertext);
+}
+async function hkdfSha256(salt, ikm, info, length) {
+  const baseKey = await globalThis.crypto.subtle.importKey(
+    "raw",
+    toUint8(ikm),
+    { name: "HKDF" },
+    false,
+    ["deriveBits"]
+  );
+  const bits = await globalThis.crypto.subtle.deriveBits(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: toUint8(salt),
+      info: toUint8(info)
+    },
+    baseKey,
+    length * 8
+  );
+  return new Uint8Array(bits);
+}
+async function buildVapidJwt({ audience, subject, publicKey, privateKey }) {
+  const header = jsonToBase64Url({ typ: "JWT", alg: "ES256" });
+  const payload = jsonToBase64Url({
+    aud: audience,
+    exp: Math.floor(Date.now() / 1e3) + VAPID_TOKEN_LIFETIME,
+    sub: subject
+  });
+  const signingInput = utf8(`${header}.${payload}`);
+  const pubBytes = base64UrlToBytes(publicKey);
+  const privBytes = base64UrlToBytes(privateKey);
+  if (pubBytes.length !== 65 || pubBytes[0] !== 4) {
+    throw new Error("VAPID publicKey must be a 65-byte uncompressed P-256 point (base64url).");
+  }
+  if (privBytes.length !== 32) {
+    throw new Error("VAPID privateKey must be a 32-byte scalar (base64url).");
+  }
+  const jwk = {
+    kty: "EC",
+    crv: "P-256",
+    d: bytesToBase64Url(privBytes),
+    x: bytesToBase64Url(pubBytes.subarray(1, 33)),
+    y: bytesToBase64Url(pubBytes.subarray(33, 65)),
+    ext: true
+  };
+  const key = await globalThis.crypto.subtle.importKey(
+    "jwk",
+    jwk,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await globalThis.crypto.subtle.sign(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    signingInput
+  );
+  return `${header}.${payload}.${bytesToBase64Url(sig)}`;
+}
+async function verifyVapidJwt(jwt, publicKey) {
+  const parts = String(jwt).split(".");
+  if (parts.length !== 3) throw new Error("VAPID JWT: malformed (expected three segments)");
+  const [h, p, s] = parts;
+  const pubBytes = base64UrlToBytes(publicKey);
+  if (pubBytes.length !== 65 || pubBytes[0] !== 4) {
+    throw new Error("VAPID publicKey must be 65 B uncompressed P-256 (base64url).");
+  }
+  const jwk = {
+    kty: "EC",
+    crv: "P-256",
+    x: bytesToBase64Url(pubBytes.subarray(1, 33)),
+    y: bytesToBase64Url(pubBytes.subarray(33, 65)),
+    ext: true
+  };
+  const key = await globalThis.crypto.subtle.importKey(
+    "jwk",
+    jwk,
+    { name: "ECDSA", namedCurve: "P-256" },
+    false,
+    ["verify"]
+  );
+  const ok = await globalThis.crypto.subtle.verify(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    base64UrlToBytes(s),
+    utf8(`${h}.${p}`)
+  );
+  if (!ok) throw new Error("VAPID JWT: signature mismatch");
+  const payload = JSON.parse(new TextDecoder().decode(base64UrlToBytes(p)));
+  if (!payload.exp || payload.exp <= Math.floor(Date.now() / 1e3)) {
+    throw new Error("VAPID JWT: expired");
+  }
+  return payload;
+}
+function originOf(endpoint) {
+  return new URL(endpoint).origin;
+}
+function writeUint32BE(buf, offset, value) {
+  buf[offset] = value >>> 24 & 255;
+  buf[offset + 1] = value >>> 16 & 255;
+  buf[offset + 2] = value >>> 8 & 255;
+  buf[offset + 3] = value & 255;
+}
+async function safeReadText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+
+// src/protocol.js
+var MULTIPART_MESSAGE_KIND = "_multipart";
+var MULTIPART_ENCODING = "json-utf8-base64url";
+var MULTIPART_VERSION = 1;
+var DEFAULT_MULTIPART_TTL_MS = 6e4;
+var DEFAULT_MULTIPART_MAX_CHUNKS = 128;
+var DEFAULT_MULTIPART_MAX_TOTAL_BYTES = 256e3;
+var REI_AMSG_POSTMESSAGE_TYPE = "REI_AMSG_PUSH";
+var REI_SW_EVENT = Object.freeze({
+  CONTENT_RECEIVED: "rei-amsg-content-received",
+  REASONING_RECEIVED: "rei-amsg-reasoning-received",
+  TOOL_REQUEST_RECEIVED: "rei-amsg-tool-request-received",
+  ERROR_RECEIVED: "rei-amsg-error-received",
+  MULTIPART_EXPIRED: "rei-amsg-multipart-expired",
+  UNKNOWN_RECEIVED: "rei-amsg-unknown-received"
+});
+var REI_SW_MESSAGE_TYPE = Object.freeze({
+  ENQUEUE_REQUEST: "REI_ENQUEUE_REQUEST",
+  DELIVER: "REI_AMSG_DELIVER",
+  FLUSH_QUEUE: "REI_FLUSH_QUEUE",
+  QUEUE_RESULT: "REI_QUEUE_RESULT"
+});
+var REI_AMSG_DELIVER_MESSAGE_TYPE = REI_SW_MESSAGE_TYPE.DELIVER;
+
 // src/index.js
 var MESSAGE_KIND = Object.freeze({
   CONTENT: "content",
@@ -201,32 +683,6 @@ function chunkReasoningByUtf8Bytes(text, maxBytes) {
   }
   return chunks;
 }
-function toUint8(buf) {
-  if (buf instanceof Uint8Array) return buf;
-  if (buf instanceof ArrayBuffer) return new Uint8Array(buf);
-  if (ArrayBuffer.isView(buf)) return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-  throw new TypeError("Expected ArrayBuffer / Uint8Array");
-}
-function base64UrlToBytes(input) {
-  const s = String(input).replace(/-/g, "+").replace(/_/g, "/");
-  const pad = (4 - s.length % 4) % 4;
-  const padded = s + "=".repeat(pad);
-  const bin = typeof atob === "function" ? atob(padded) : Buffer.from(padded, "base64").toString("binary");
-  const out = new Uint8Array(bin.length);
-  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
-  return out;
-}
-function concatBytes(...chunks) {
-  let total = 0;
-  for (const c of chunks) total += c.byteLength;
-  const out = new Uint8Array(total);
-  let offset = 0;
-  for (const c of chunks) {
-    out.set(c instanceof Uint8Array ? c : new Uint8Array(c.buffer || c), offset);
-    offset += c.byteLength;
-  }
-  return out;
-}
 function isValidUrl(value) {
   if (typeof value !== "string") return false;
   try {
@@ -459,28 +915,57 @@ function stringifyDecisionForError(value) {
 }
 export {
   AVATAR_URL_MAX_LENGTH,
+  DEFAULT_MULTIPART_MAX_CHUNKS,
+  DEFAULT_MULTIPART_MAX_TOTAL_BYTES,
+  DEFAULT_MULTIPART_TTL_MS,
+  LLM_MESSAGES_ERROR,
   MESSAGE_KIND,
   MESSAGE_TYPE,
+  MULTIPART_ENCODING,
+  MULTIPART_MESSAGE_KIND,
+  MULTIPART_VERSION,
   PUSH_SOURCE,
+  REI_AMSG_DELIVER_MESSAGE_TYPE,
+  REI_AMSG_POSTMESSAGE_TYPE,
+  REI_SW_EVENT,
+  REI_SW_MESSAGE_TYPE,
   assertValidDecision,
   base64UrlToBytes,
   buildContentPush,
   buildErrorPush,
+  buildLlmRequestBody,
   buildReasoningPush,
   buildSessionContext,
   buildToolRequestPush,
+  buildVapidJwt,
+  bytesToBase64,
+  bytesToBase64Url,
+  bytesToHex,
+  callLlm,
   chunkReasoningByUtf8Bytes,
   concatBytes,
   extractAssistantMessage,
   extractToolCallsFromDecision,
+  hexToBytes,
+  hmacSha256,
   isContentPush,
   isErrorPush,
   isReasoningPush,
   isToolRequestPush,
   isValidUrl,
+  jsonToBase64Url,
+  normalizeAiApiUrl,
   normalizeVapidSubject,
+  randomBytes,
+  randomUUID,
   readReasoningContent,
+  sendWebPush,
   stripReasoningTags,
+  timingSafeEqualBytes,
   toUint8,
-  validateAvatarUrl
+  utf8,
+  utf8Decode,
+  validateAvatarUrl,
+  validateLlmMessagesShape,
+  verifyVapidJwt
 };

package/dist/llm-call.d.cts

@@ -0,0 +1,113 @@
+/**
+ * OpenAI-compatible LLM HTTP 调用核心 — 单一事实来源。
+ *
+ * `@rei-standard/amsg-instant`（message-processor 的 callLlmRaw）与
+ * `@rei-standard/amsg-server`（lib/llm.js 的 callLlm）此前各写一份
+ * 「构造请求体 + fetch + 超时 + 解析响应 + trim」，并已出现漂移
+ * （stream 字段、messages 模式探测、超时可配性）。现在公共核心收敛到
+ * 这里，两侧差异通过 options 参数化，各包保留自己的导出名与错误码
+ * 包装：
+ *
+ *   - `stream`       — instant 传 `false`（一次性、非流式契约，字段显式
+ *                      出现在请求体里）；server 不传（字段缺省，行为与
+ *                      之前逐字节一致）。
+ *   - `forwardTools` — server 转发 payload.tools / payload.toolChoice
+ *                      （v2.6.0 起）；instant 传 `false` 维持既有
+ *                      「忽略 tools」行为。
+ *   - `timeoutMs`    — server 的 agentic 循环传剩余墙钟预算；instant 传
+ *                      300000 维持现状。默认 300000。
+ *
+ * messages 模式探测统一为 `Array.isArray(payload.messages) &&
+ * payload.messages.length > 0`（server 语义）：`messages: []` 回退
+ * completePrompt 模式，而不是把空数组原样发给上游。
+ */
+/**
+ * Call an OpenAI-compatible API.
+ *
+ * Returns the full response object alongside the extracted (trimmed)
+ * `content` string. Callers that only need the text can ignore
+ * `response`; callers that want `reasoning_content` / `tool_calls`
+ * read from `response.choices[0].message`.
+ *
+ * @param {Object} payload
+ * @param {{
+ *   requireContent?: boolean,
+ *   timeoutMs?: number,
+ *   fetch?: typeof globalThis.fetch,
+ *   stream?: boolean,
+ *   forwardTools?: boolean,
+ * }} [options]
+ *   requireContent defaults to true (legacy single-shot behavior:
+ *   throw when the response carries no content). Tool rounds legitimately
+ *   return no content (pure tool_calls), so agentic loops pass
+ *   `{ requireContent: false }`.
+ *   timeoutMs defaults to 300000 (the legacy per-call ceiling).
+ *   fetch defaults to `globalThis.fetch` (resolved at call time so test
+ *   stubs on the global still take effect).
+ *   stream / forwardTools are forwarded to {@link buildLlmRequestBody}.
+ * @returns {Promise<{ response: unknown, content: string }>}
+ */
+export function callLlm(payload: any, options?: {
+    requireContent?: boolean;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+    stream?: boolean;
+    forwardTools?: boolean;
+}): Promise<{
+    response: unknown;
+    content: string;
+}>;
+/**
+ * Build OpenAI-compatible request body.
+ *
+ * messages mode: forward the caller's OpenAI-style array verbatim — no
+ * auto role injection, no concatenation back to a single user message.
+ * Lets the upstream app preserve system / multi-turn context
+ * byte-for-byte. A missing / empty `payload.messages` falls back to
+ * wrapping `payload.completePrompt` into a single user message.
+ *
+ * `temperature`: only inject the 0.8 default for the legacy
+ * completePrompt path; messages mode forwards whatever the upstream app
+ * set (or nothing) so behavior matches their main chat path.
+ *
+ * `max_tokens` is optional:
+ * - include it only when payload.maxTokens is provided
+ * - omit it when payload.maxTokens is undefined / null
+ *
+ * `tools` / `tool_choice` are optional as well: forwarded only when
+ * `options.forwardTools` is not `false` and the caller passes a
+ * non-empty payload.tools. An empty array is treated as "no tools"
+ * because some OpenAI-compatible relays reject `tools: []`.
+ *
+ * @param {Object} payload
+ * @param {{ stream?: boolean, forwardTools?: boolean }} [options]
+ *   stream — set to include an explicit `stream` field in the body
+ *   (instant passes `false`: one-shot, non-streaming by contract);
+ *   omit to leave the field out entirely (server behavior).
+ * @returns {Object}
+ */
+export function buildLlmRequestBody(payload: any, options?: {
+    stream?: boolean;
+    forwardTools?: boolean;
+}): any;
+/**
+ * Normalize the AI API URL for OpenAI-compatible chat endpoints.
+ *
+ * Rules (idempotent — running it twice is the same as running it once):
+ *   - Already ends with `/chat/completions`           → leave as-is.
+ *   - Bare host (no path or just `/`)                  → append `/v1/chat/completions`.
+ *   - Path ends with a version segment like `/v1`,
+ *     `/v2`, … (with or without trailing slash)       → append only `/chat/completions`
+ *     (never doubles `/v1` for callers who already
+ *      include it).
+ *   - Anything else (custom path that doesn't match
+ *     the OpenAI shape, e.g. `/v1/messages` for
+ *     Anthropic-style proxies, or `/openai/api/foo`)   → leave as-is. We don't
+ *     guess — the caller knows their own routing.
+ *
+ * The query string is preserved verbatim.
+ *
+ * @param {string} apiUrl
+ * @returns {string}
+ */
+export function normalizeAiApiUrl(apiUrl: string): string;