@rei-standard/amsg-server 2.1.0 → 2.2.0

package/README.md

@@ -50,6 +50,10 @@ const rei = await createReiServer({
 // GET  /api/v1/messages             -> rei.handlers.messages.GET
 ```
 
+## 关于 `messageType: 'instant'`
+
+> **Note**：新代码的 instant 消息请用 [@rei-standard/amsg-instant](../instant/README.md)，跳过本端点的"建任务 → 处理 → 删任务" DB 来回。本端点的 `instant` 分支为兼容保留，行为不变、不会有运行时警告。
+
 ## AI 接口 `apiUrl` 约束
 
 当 `messageType` 为 `prompted` / `auto`，或 `instant` 使用 AI 配置时：
@@ -61,6 +65,21 @@ const rei = await createReiServer({
 
 如果上游返回 `405 Method Not Allowed`，通常表示 `apiUrl` 指向了基础域名而非聊天端点，请优先检查配置值。
 
+## 提示词字段（`completePrompt` vs `messages`，2.2.0+）
+
+AI 配置消息的提示词可以用两种形态之一，**互斥二选一**：
+
+- `completePrompt: string` —— 简单场景：内部包成单条 `{role:'user', content}` 后发给 LLM。
+- `messages: Array<{ role: 'system'|'user'|'assistant'|'tool', content: string | unknown[] }>` —— 多轮 / 带 system role：**原样**转发给 LLM，不做任何 role 注入或重排。和上游主聊天路径调用 LLM 的 body 字节级一致。
+
+两个字段同时给 → `400 INVALID_PARAMETERS`；都不给且没 `userMessage`（仅 instant 类型允许 fallback）也是 400。`messages` 数组必须非空，role 必须是上面四种之一。
+
+可选 `temperature?: number` 透传给 LLM：`completePrompt` 路径未传时默认 0.8（保持旧行为）；`messages` 路径未传时**不发**，让上游主路径自己决定。
+
+## 导出（新增）
+
+- `validateLlmMessagesArray(messages)` — 同步预校验 messages 数组，返回 `string | null`（错误信息 / 通过）。和 `@rei-standard/amsg-instant` 的校验规则字节级一致。
+
 ## 一体化初始化流程
 
 1. 管理员配置环境变量（VAPID + tenant secrets）

package/dist/index.cjs

@@ -47,6 +47,29 @@ function isValidUUIDv4(uuid) {
   const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
   return uuidV4Regex.test(uuid);
 }
+var VALID_LLM_MESSAGE_ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant", "tool"]);
+function validateLlmMessagesArray(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return "messages must be a non-empty array";
+  }
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (!m || typeof m !== "object" || Array.isArray(m)) {
+      return `messages[${i}] must be an object`;
+    }
+    if (!VALID_LLM_MESSAGE_ROLES.has(m.role)) {
+      return `messages[${i}].role must be one of system / user / assistant / tool`;
+    }
+    if (typeof m.content === "string") {
+      if (!m.content) return `messages[${i}].content must be a non-empty string`;
+    } else if (Array.isArray(m.content)) {
+      if (m.content.length === 0) return `messages[${i}].content array must be non-empty`;
+    } else {
+      return `messages[${i}].content must be a non-empty string or a non-empty array`;
+    }
+  }
+  return null;
+}
 function validateScheduleMessagePayload(payload) {
   if (!payload.contactName || typeof payload.contactName !== "string") {
     return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { missingFields: ["contactName"] } };
@@ -74,9 +97,35 @@ function validateScheduleMessagePayload(payload) {
       return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { missingFields: ["userMessage (required for fixed type)"] } };
     }
   }
+  const promptCheck = (() => {
+    const hasCompletePrompt = payload.completePrompt !== void 0 && payload.completePrompt !== null && payload.completePrompt !== "";
+    const hasMessages = payload.messages !== void 0 && payload.messages !== null;
+    if (hasCompletePrompt && hasMessages) {
+      return {
+        error: { code: "INVALID_PARAMETERS", message: "exactly one of `completePrompt` or `messages` must be provided\uFF08\u4E24\u8005\u4E0D\u80FD\u540C\u65F6\u51FA\u73B0\uFF09", details: { invalidFields: ["completePrompt", "messages"] } },
+        hasCompletePrompt: true,
+        hasMessages: true
+      };
+    }
+    if (hasMessages) {
+      const err = validateLlmMessagesArray(payload.messages);
+      if (err) {
+        return {
+          error: { code: "INVALID_PARAMETERS", message: err, details: { invalidFields: ["messages"] } },
+          hasCompletePrompt: false,
+          hasMessages: true
+        };
+      }
+    }
+    return { error: null, hasCompletePrompt, hasMessages };
+  })();
+  if (promptCheck.error) {
+    return { valid: false, errorCode: promptCheck.error.code, errorMessage: promptCheck.error.message, details: promptCheck.error.details };
+  }
+  const hasPrompt = promptCheck.hasCompletePrompt || promptCheck.hasMessages;
   if (payload.messageType === "prompted" || payload.messageType === "auto") {
     const missingAiFields = [];
-    if (!payload.completePrompt) missingAiFields.push("completePrompt");
+    if (!hasPrompt) missingAiFields.push("completePrompt or messages");
     if (!payload.apiUrl) missingAiFields.push("apiUrl");
     if (!payload.apiKey) missingAiFields.push("apiKey");
     if (!payload.primaryModel) missingAiFields.push("primaryModel");
@@ -88,12 +137,15 @@ function validateScheduleMessagePayload(payload) {
     if (payload.recurrenceType && payload.recurrenceType !== "none") {
       return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "instant \u7C7B\u578B\u7684 recurrenceType \u5FC5\u987B\u4E3A none", details: { invalidFields: ['recurrenceType (must be "none" for instant type)'] } };
     }
-    const hasAiConfig = payload.completePrompt && payload.apiUrl && payload.apiKey && payload.primaryModel;
+    const hasAiConfig = hasPrompt && payload.apiUrl && payload.apiKey && payload.primaryModel;
     const hasUserMessage = payload.userMessage;
     if (!hasAiConfig && !hasUserMessage) {
-      return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "instant \u7C7B\u578B\u5FC5\u987B\u63D0\u4F9B userMessage \u6216\u5B8C\u6574\u7684 AI \u914D\u7F6E", details: { missingFields: ["userMessage or (completePrompt + apiUrl + apiKey + primaryModel)"] } };
+      return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "instant \u7C7B\u578B\u5FC5\u987B\u63D0\u4F9B userMessage \u6216\u5B8C\u6574\u7684 AI \u914D\u7F6E", details: { missingFields: ["userMessage or ((completePrompt | messages) + apiUrl + apiKey + primaryModel)"] } };
     }
   }
+  if (payload.temperature !== void 0 && payload.temperature !== null && (typeof payload.temperature !== "number" || !Number.isFinite(payload.temperature))) {
+    return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["temperature (must be a finite number)"] } };
+  }
   if (payload.avatarUrl && !isValidUrl(payload.avatarUrl)) {
     return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["avatarUrl (invalid URL format)"] } };
   }
@@ -395,7 +447,8 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
     if (decryptedPayload.messageType === "fixed") {
       messageContent = decryptedPayload.userMessage;
     } else if (decryptedPayload.messageType === "instant") {
-      if (decryptedPayload.completePrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
+      const hasPrompt = !!decryptedPayload.completePrompt || Array.isArray(decryptedPayload.messages) && decryptedPayload.messages.length > 0;
+      if (hasPrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
         messageContent = await _callAI(decryptedPayload);
       } else if (decryptedPayload.userMessage) {
         messageContent = decryptedPayload.userMessage;
@@ -537,11 +590,16 @@ async function _callAI(payload) {
   return content.trim();
 }
 function buildAiRequestBody(payload) {
+  const llmMessages = Array.isArray(payload.messages) && payload.messages.length > 0 ? payload.messages : [{ role: "user", content: payload.completePrompt }];
   const requestBody = {
     model: payload.primaryModel,
-    messages: [{ role: "user", content: payload.completePrompt }],
-    temperature: 0.8
+    messages: llmMessages
   };
+  if (payload.temperature !== void 0 && payload.temperature !== null) {
+    requestBody.temperature = payload.temperature;
+  } else if (!Array.isArray(payload.messages)) {
+    requestBody.temperature = 0.8;
+  }
   if (payload.maxTokens === void 0 || payload.maxTokens === null) {
     return requestBody;
   }
@@ -554,7 +612,7 @@ function buildAiRequestBody(payload) {
 function normalizeAiApiUrl(apiUrl) {
   if (typeof apiUrl !== "string" || !apiUrl.trim()) {
     throw new Error(
-      "Invalid apiUrl: apiUrl is required. Please provide a full chat endpoint URL (for example: https://api.openai.com/v1/chat/completions)."
+      "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)."
     );
   }
   const trimmedApiUrl = apiUrl.trim();
@@ -563,10 +621,17 @@ function normalizeAiApiUrl(apiUrl) {
     parsedUrl = new URL(trimmedApiUrl);
   } catch (e3) {
     throw new Error(
-      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL that points to a full chat endpoint.`
+      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
     );
   }
-  parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, "") || "/";
+  let path = parsedUrl.pathname.replace(/\/+$/, "") || "/";
+  if (/\/chat\/completions$/.test(path)) {
+  } else if (path === "/") {
+    path = "/v1/chat/completions";
+  } else if (/\/v\d+$/.test(path)) {
+    path = `${path}/chat/completions`;
+  }
+  parsedUrl.pathname = path;
   return parsedUrl.toString();
 }
 
@@ -634,8 +699,13 @@ function createScheduleMessageHandler(ctx) {
       apiUrl: payload.apiUrl || null,
       apiKey: payload.apiKey || null,
       primaryModel: payload.primaryModel || null,
+      // Prompt is one-of: legacy completePrompt (string) OR messages (OpenAI-
+      // style array). Validation has already enforced exactly-one-of, so
+      // exactly one of these will be non-null when an AI config is provided.
       completePrompt: payload.completePrompt || null,
+      messages: Array.isArray(payload.messages) ? payload.messages : null,
       maxTokens: _nullishCoalesce(payload.maxTokens, () => ( null)),
+      temperature: _nullishCoalesce(payload.temperature, () => ( null)),
       pushSubscription: payload.pushSubscription,
       metadata: payload.metadata || {}
     };
@@ -947,6 +1017,18 @@ function createUpdateMessageHandler(ctx) {
     if (Object.prototype.hasOwnProperty.call(updates, "maxTokens") && updates.maxTokens !== null && (!Number.isInteger(updates.maxTokens) || updates.maxTokens <= 0)) {
       return { status: 400, body: { success: false, error: { code: "INVALID_UPDATE_DATA", message: "\u66F4\u65B0\u6570\u636E\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["maxTokens"] } } } };
     }
+    if (updates.completePrompt && updates.messages !== void 0 && updates.messages !== null) {
+      return { status: 400, body: { success: false, error: { code: "INVALID_UPDATE_DATA", message: "completePrompt \u4E0E messages \u4E0D\u80FD\u540C\u65F6\u66F4\u65B0\uFF08\u4E8C\u9009\u4E00\uFF09", details: { invalidFields: ["completePrompt", "messages"] } } } };
+    }
+    if (updates.messages !== void 0 && updates.messages !== null) {
+      const msgErr = validateLlmMessagesArray(updates.messages);
+      if (msgErr) {
+        return { status: 400, body: { success: false, error: { code: "INVALID_UPDATE_DATA", message: msgErr, details: { invalidFields: ["messages"] } } } };
+      }
+    }
+    if (Object.prototype.hasOwnProperty.call(updates, "temperature") && updates.temperature !== null && (typeof updates.temperature !== "number" || !Number.isFinite(updates.temperature))) {
+      return { status: 400, body: { success: false, error: { code: "INVALID_UPDATE_DATA", message: "\u66F4\u65B0\u6570\u636E\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["temperature"] } } } };
+    }
     const existingTask = await db.getTaskByUuid(taskUuid, userId);
     if (!existingTask) {
       const taskStatus = await db.getTaskStatus(taskUuid, userId);
@@ -956,14 +1038,23 @@ function createUpdateMessageHandler(ctx) {
       return { status: 409, body: { success: false, error: { code: "TASK_ALREADY_COMPLETED", message: "\u4EFB\u52A1\u5DF2\u5B8C\u6210\u6216\u5DF2\u5931\u8D25\uFF0C\u65E0\u6CD5\u66F4\u65B0" } } };
     }
     const existingData = JSON.parse(decryptFromStorage(existingTask.encrypted_payload, userKey));
+    const promptUpdates = {};
+    if (updates.completePrompt) {
+      promptUpdates.completePrompt = updates.completePrompt;
+      promptUpdates.messages = null;
+    } else if (updates.messages !== void 0 && updates.messages !== null) {
+      promptUpdates.messages = updates.messages;
+      promptUpdates.completePrompt = null;
+    }
     const updatedData = {
       ...existingData,
-      ...updates.completePrompt && { completePrompt: updates.completePrompt },
+      ...promptUpdates,
       ...updates.userMessage && { userMessage: updates.userMessage },
       ...updates.recurrenceType && { recurrenceType: updates.recurrenceType },
       ...updates.avatarUrl && { avatarUrl: updates.avatarUrl },
       ...updates.metadata && { metadata: updates.metadata },
-      ...Object.prototype.hasOwnProperty.call(updates, "maxTokens") && { maxTokens: _nullishCoalesce(updates.maxTokens, () => ( null)) }
+      ...Object.prototype.hasOwnProperty.call(updates, "maxTokens") && { maxTokens: _nullishCoalesce(updates.maxTokens, () => ( null)) },
+      ...Object.prototype.hasOwnProperty.call(updates, "temperature") && { temperature: _nullishCoalesce(updates.temperature, () => ( null)) }
     };
     const encryptedPayload = encryptForStorage(JSON.stringify(updatedData), userKey);
     const extraFields = updates.nextSendAt ? { next_send_at: updates.nextSendAt } : void 0;
@@ -1486,4 +1577,5 @@ async function createReiServer(config) {
 
 
 
-exports.createAdapter = createAdapter; exports.createReiServer = createReiServer; exports.createTenantToken = createTenantToken; exports.decryptFromStorage = decryptFromStorage; exports.decryptPayload = decryptPayload; exports.deriveUserEncryptionKey = deriveUserEncryptionKey; exports.encryptForStorage = encryptForStorage; exports.isValidISO8601 = isValidISO8601; exports.isValidUUID = isValidUUID; exports.isValidUUIDv4 = isValidUUIDv4; exports.isValidUrl = isValidUrl; exports.validateScheduleMessagePayload = validateScheduleMessagePayload; exports.verifyTenantToken = verifyTenantToken;
+
+exports.createAdapter = createAdapter; exports.createReiServer = createReiServer; exports.createTenantToken = createTenantToken; exports.decryptFromStorage = decryptFromStorage; exports.decryptPayload = decryptPayload; exports.deriveUserEncryptionKey = deriveUserEncryptionKey; exports.encryptForStorage = encryptForStorage; exports.isValidISO8601 = isValidISO8601; exports.isValidUUID = isValidUUID; exports.isValidUUIDv4 = isValidUUIDv4; exports.isValidUrl = isValidUrl; exports.validateLlmMessagesArray = validateLlmMessagesArray; exports.validateScheduleMessagePayload = validateScheduleMessagePayload; exports.verifyTenantToken = verifyTenantToken;

package/dist/index.d.cts

@@ -101,6 +101,40 @@ function isValidUUIDv4(uuid) {
   return uuidV4Regex.test(uuid);
 }
 
+const VALID_LLM_MESSAGE_ROLES = new Set(['system', 'user', 'assistant', 'tool']);
+
+/**
+ * Validate an OpenAI-style messages array. Same shape contract as
+ * `@rei-standard/amsg-instant` (kept in lockstep on purpose — both packages
+ * end up forwarding this to the same LLM body).
+ *
+ * @param {unknown} messages
+ * @returns {string | null}   Error message, or null if valid.
+ */
+function validateLlmMessagesArray(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return 'messages must be a non-empty array';
+  }
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (!m || typeof m !== 'object' || Array.isArray(m)) {
+      return `messages[${i}] must be an object`;
+    }
+    if (!VALID_LLM_MESSAGE_ROLES.has(m.role)) {
+      return `messages[${i}].role must be one of system / user / assistant / tool`;
+    }
+    if (typeof m.content === 'string') {
+      if (!m.content) return `messages[${i}].content must be a non-empty string`;
+    } else if (Array.isArray(m.content)) {
+      if (m.content.length === 0) return `messages[${i}].content array must be non-empty`;
+      // Element schema is intentionally not enforced — passed through to LLM as-is.
+    } else {
+      return `messages[${i}].content must be a non-empty string or a non-empty array`;
+    }
+  }
+  return null;
+}
+
 /**
  * Validate the schedule-message request payload.
  *
@@ -146,9 +180,40 @@ function validateScheduleMessagePayload(payload) {
     }
   }
 
+  // ─── Prompt schema (shared by prompted / auto / instant AI configs) ──
+  //
+  // Callers provide *exactly one of* `completePrompt` (string) or `messages`
+  // (OpenAI-style array). Same contract as @rei-standard/amsg-instant; the
+  // server's LLM path forwards either verbatim.
+  const promptCheck = (() => {
+    const hasCompletePrompt = payload.completePrompt !== undefined && payload.completePrompt !== null && payload.completePrompt !== '';
+    const hasMessages = payload.messages !== undefined && payload.messages !== null;
+    if (hasCompletePrompt && hasMessages) {
+      return {
+        error: { code: 'INVALID_PARAMETERS', message: 'exactly one of `completePrompt` or `messages` must be provided（两者不能同时出现）', details: { invalidFields: ['completePrompt', 'messages'] } },
+        hasCompletePrompt: true, hasMessages: true,
+      };
+    }
+    if (hasMessages) {
+      const err = validateLlmMessagesArray(payload.messages);
+      if (err) {
+        return {
+          error: { code: 'INVALID_PARAMETERS', message: err, details: { invalidFields: ['messages'] } },
+          hasCompletePrompt: false, hasMessages: true,
+        };
+      }
+    }
+    return { error: null, hasCompletePrompt, hasMessages };
+  })();
+
+  if (promptCheck.error) {
+    return { valid: false, errorCode: promptCheck.error.code, errorMessage: promptCheck.error.message, details: promptCheck.error.details };
+  }
+  const hasPrompt = promptCheck.hasCompletePrompt || promptCheck.hasMessages;
+
   if (payload.messageType === 'prompted' || payload.messageType === 'auto') {
     const missingAiFields = [];
-    if (!payload.completePrompt) missingAiFields.push('completePrompt');
+    if (!hasPrompt) missingAiFields.push('completePrompt or messages');
     if (!payload.apiUrl) missingAiFields.push('apiUrl');
     if (!payload.apiKey) missingAiFields.push('apiKey');
     if (!payload.primaryModel) missingAiFields.push('primaryModel');
@@ -161,13 +226,21 @@ function validateScheduleMessagePayload(payload) {
     if (payload.recurrenceType && payload.recurrenceType !== 'none') {
       return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: 'instant 类型的 recurrenceType 必须为 none', details: { invalidFields: ['recurrenceType (must be "none" for instant type)'] } };
     }
-    const hasAiConfig = payload.completePrompt && payload.apiUrl && payload.apiKey && payload.primaryModel;
+    const hasAiConfig = hasPrompt && payload.apiUrl && payload.apiKey && payload.primaryModel;
     const hasUserMessage = payload.userMessage;
     if (!hasAiConfig && !hasUserMessage) {
-      return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: 'instant 类型必须提供 userMessage 或完整的 AI 配置', details: { missingFields: ['userMessage or (completePrompt + apiUrl + apiKey + primaryModel)'] } };
+      return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: 'instant 类型必须提供 userMessage 或完整的 AI 配置', details: { missingFields: ['userMessage or ((completePrompt | messages) + apiUrl + apiKey + primaryModel)'] } };
     }
   }
 
+  if (
+    payload.temperature !== undefined &&
+    payload.temperature !== null &&
+    (typeof payload.temperature !== 'number' || !Number.isFinite(payload.temperature))
+  ) {
+    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['temperature (must be a finite number)'] } };
+  }
+
   if (payload.avatarUrl && !isValidUrl(payload.avatarUrl)) {
     return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['avatarUrl (invalid URL format)'] } };
   }
@@ -681,7 +754,8 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
       messageContent = decryptedPayload.userMessage;
 
     } else if (decryptedPayload.messageType === 'instant') {
-      if (decryptedPayload.completePrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
+      const hasPrompt = !!decryptedPayload.completePrompt || (Array.isArray(decryptedPayload.messages) && decryptedPayload.messages.length > 0);
+      if (hasPrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
         messageContent = await _callAI(decryptedPayload);
       } else if (decryptedPayload.userMessage) {
         messageContent = decryptedPayload.userMessage;
@@ -887,12 +961,29 @@ async function _callAI(payload) {
  * @returns {Object}
  */
 function buildAiRequestBody(payload) {
+  // messages mode (added in v2.2.0): forward the caller's OpenAI-style array
+  // verbatim — same contract as @rei-standard/amsg-instant 0.5.0+. No auto
+  // role injection, no concatenation back to a single user message. Lets
+  // the upstream app preserve system / multi-turn context byte-for-byte
+  // across the schedule-message path.
+  const llmMessages = Array.isArray(payload.messages) && payload.messages.length > 0
+    ? payload.messages
+    : [{ role: 'user', content: payload.completePrompt }];
+
   const requestBody = {
     model: payload.primaryModel,
-    messages: [{ role: 'user', content: payload.completePrompt }],
-    temperature: 0.8
+    messages: llmMessages,
   };
 
+  // Match the instant package's behavior: only inject default temperature
+  // for the legacy completePrompt path; messages mode forwards whatever the
+  // upstream app set (or nothing) so behavior matches their main chat path.
+  if (payload.temperature !== undefined && payload.temperature !== null) {
+    requestBody.temperature = payload.temperature;
+  } else if (!Array.isArray(payload.messages)) {
+    requestBody.temperature = 0.8;
+  }
+
   if (payload.maxTokens === undefined || payload.maxTokens === null) {
     return requestBody;
   }
@@ -906,12 +997,27 @@ function buildAiRequestBody(payload) {
 }
 
 /**
- * Normalize AI API URL with minimal, non-breaking rules:
- * - trim whitespace
- * - remove redundant trailing slashes from pathname
- * - keep query string untouched
+ * Normalize AI API URL for OpenAI-compatible chat endpoints.
+ *
+ * **Keep in sync** with `@rei-standard/amsg-instant`'s
+ * `src/message-processor.js` `normalizeAiApiUrl` — same rules, same
+ * tests. The two packages share this logic but each carry their own copy
+ * to avoid an architectural dependency (server should not depend on the
+ * stateless worker package).
  *
- * Note: This function does NOT auto-append /v1 or /chat/completions.
+ * Rules (idempotent — running it twice equals 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)                          → leave as-is. The caller
+ *     knows their own routing.
+ *
+ * Query string is preserved verbatim.
  *
  * @param {string} apiUrl
  * @returns {string}
@@ -920,7 +1026,8 @@ function normalizeAiApiUrl(apiUrl) {
   if (typeof apiUrl !== 'string' || !apiUrl.trim()) {
     throw new Error(
       'Invalid apiUrl: apiUrl is required. ' +
-      'Please provide a full chat endpoint URL (for example: https://api.openai.com/v1/chat/completions).'
+      'Please provide a chat endpoint URL ' +
+      '(for example: https://api.openai.com or https://api.openai.com/v1/chat/completions).'
     );
   }
 
@@ -931,12 +1038,23 @@ function normalizeAiApiUrl(apiUrl) {
     parsedUrl = new URL(trimmedApiUrl);
   } catch {
     throw new Error(
-      `Invalid apiUrl: "${apiUrl}". ` +
-      'Please provide a valid absolute URL that points to a full chat endpoint.'
+      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
     );
   }
 
-  parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, '') || '/';
+  let path = parsedUrl.pathname.replace(/\/+$/, '') || '/';
+
+  if (/\/chat\/completions$/.test(path)) ; else if (path === '/') {
+    // Bare host → assume OpenAI shape.
+    path = '/v1/chat/completions';
+  } else if (/\/v\d+$/.test(path)) {
+    // Path ends in `/v1`, `/v2`, … — caller already versioned the URL.
+    // Append only `/chat/completions`; never re-add `/v1`.
+    path = `${path}/chat/completions`;
+  }
+  // Any other custom path is left untouched on purpose.
+
+  parsedUrl.pathname = path;
   return parsedUrl.toString();
 }
 
@@ -1025,14 +1143,27 @@ function createScheduleMessageHandler(ctx) {
       apiUrl: payload.apiUrl || null,
       apiKey: payload.apiKey || null,
       primaryModel: payload.primaryModel || null,
+      // Prompt is one-of: legacy completePrompt (string) OR messages (OpenAI-
+      // style array). Validation has already enforced exactly-one-of, so
+      // exactly one of these will be non-null when an AI config is provided.
       completePrompt: payload.completePrompt || null,
+      messages: Array.isArray(payload.messages) ? payload.messages : null,
       maxTokens: payload.maxTokens ?? null,
+      temperature: payload.temperature ?? null,
       pushSubscription: payload.pushSubscription,
       metadata: payload.metadata || {}
     };
 
     const encryptedPayload = encryptForStorage(JSON.stringify(fullTaskData), userKey);
 
+    /**
+     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
+     *   This branch is kept for backward compatibility and the existing behavior
+     *   (create task → process → delete) is unchanged. The dedicated amsg-instant
+     *   package is stateless (no DB roundtrip), deployable to Cloudflare Workers,
+     *   and locks the encryption + push-payload contract behind a single version.
+     *   See packages/rei-standard-amsg/instant/README.md.
+     */
     // Instant type: check VAPID before creating the task to avoid orphaned rows
     if (payload.messageType === 'instant') {
       if (!ctx.vapid.email || !ctx.vapid.publicKey || !ctx.vapid.privateKey) {
@@ -1086,6 +1217,13 @@ function createScheduleMessageHandler(ctx) {
       return { status: 500, body: { success: false, error: { code: 'TASK_CREATE_FAILED', message: '创建任务失败' } } };
     }
 
+    /**
+     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
+     *   The "create-task → process-by-uuid → delete-task" sequence below is
+     *   preserved verbatim so existing clients keep working. New integrations
+     *   should call the dedicated amsg-instant endpoint instead — it skips this
+     *   DB round-trip entirely. See packages/rei-standard-amsg/instant/README.md.
+     */
     // Instant type: send immediately
     if (payload.messageType === 'instant') {
       try {
@@ -1408,6 +1546,30 @@ function createUpdateMessageHandler(ctx) {
       return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: '更新数据格式错误', details: { invalidFields: ['maxTokens'] } } } };
     }
 
+    // Reject updates that try to set both completePrompt and messages at
+    // once. We don't enforce one-of-required here (callers may patch other
+    // fields), but the two prompt sources are mutually exclusive and must
+    // stay that way in storage too.
+    if (
+      updates.completePrompt &&
+      updates.messages !== undefined && updates.messages !== null
+    ) {
+      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: 'completePrompt 与 messages 不能同时更新（二选一）', details: { invalidFields: ['completePrompt', 'messages'] } } } };
+    }
+    if (updates.messages !== undefined && updates.messages !== null) {
+      const msgErr = validateLlmMessagesArray(updates.messages);
+      if (msgErr) {
+        return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: msgErr, details: { invalidFields: ['messages'] } } } };
+      }
+    }
+    if (
+      Object.prototype.hasOwnProperty.call(updates, 'temperature') &&
+      updates.temperature !== null &&
+      (typeof updates.temperature !== 'number' || !Number.isFinite(updates.temperature))
+    ) {
+      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: '更新数据格式错误', details: { invalidFields: ['temperature'] } } } };
+    }
+
     // Fetch existing task
     const existingTask = await db.getTaskByUuid(taskUuid, userId);
 
@@ -1421,14 +1583,27 @@ function createUpdateMessageHandler(ctx) {
 
     const existingData = JSON.parse(decryptFromStorage(existingTask.encrypted_payload, userKey));
 
+    // When the caller switches prompt source (completePrompt ↔ messages),
+    // null out the other so storage stays one-of (matches schedule-message
+    // shape and prevents buildAiRequestBody from accidentally seeing both).
+    const promptUpdates = {};
+    if (updates.completePrompt) {
+      promptUpdates.completePrompt = updates.completePrompt;
+      promptUpdates.messages = null;
+    } else if (updates.messages !== undefined && updates.messages !== null) {
+      promptUpdates.messages = updates.messages;
+      promptUpdates.completePrompt = null;
+    }
+
     const updatedData = {
       ...existingData,
-      ...(updates.completePrompt && { completePrompt: updates.completePrompt }),
+      ...promptUpdates,
       ...(updates.userMessage && { userMessage: updates.userMessage }),
       ...(updates.recurrenceType && { recurrenceType: updates.recurrenceType }),
       ...(updates.avatarUrl && { avatarUrl: updates.avatarUrl }),
       ...(updates.metadata && { metadata: updates.metadata }),
-      ...(Object.prototype.hasOwnProperty.call(updates, 'maxTokens') && { maxTokens: updates.maxTokens ?? null })
+      ...(Object.prototype.hasOwnProperty.call(updates, 'maxTokens') && { maxTokens: updates.maxTokens ?? null }),
+      ...(Object.prototype.hasOwnProperty.call(updates, 'temperature') && { temperature: updates.temperature ?? null })
     };
 
     const encryptedPayload = encryptForStorage(JSON.stringify(updatedData), userKey);
@@ -2162,4 +2337,4 @@ async function createReiServer(config) {
   };
 }
 
-export { createAdapter, createReiServer, createTenantToken, decryptFromStorage, decryptPayload, deriveUserEncryptionKey, encryptForStorage, isValidISO8601, isValidUUID, isValidUUIDv4, isValidUrl, validateScheduleMessagePayload, verifyTenantToken };
+export { createAdapter, createReiServer, createTenantToken, decryptFromStorage, decryptPayload, deriveUserEncryptionKey, encryptForStorage, isValidISO8601, isValidUUID, isValidUUIDv4, isValidUrl, validateLlmMessagesArray, validateScheduleMessagePayload, verifyTenantToken };

package/dist/index.d.ts

@@ -101,6 +101,40 @@ function isValidUUIDv4(uuid) {
   return uuidV4Regex.test(uuid);
 }
 
+const VALID_LLM_MESSAGE_ROLES = new Set(['system', 'user', 'assistant', 'tool']);
+
+/**
+ * Validate an OpenAI-style messages array. Same shape contract as
+ * `@rei-standard/amsg-instant` (kept in lockstep on purpose — both packages
+ * end up forwarding this to the same LLM body).
+ *
+ * @param {unknown} messages
+ * @returns {string | null}   Error message, or null if valid.
+ */
+function validateLlmMessagesArray(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return 'messages must be a non-empty array';
+  }
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (!m || typeof m !== 'object' || Array.isArray(m)) {
+      return `messages[${i}] must be an object`;
+    }
+    if (!VALID_LLM_MESSAGE_ROLES.has(m.role)) {
+      return `messages[${i}].role must be one of system / user / assistant / tool`;
+    }
+    if (typeof m.content === 'string') {
+      if (!m.content) return `messages[${i}].content must be a non-empty string`;
+    } else if (Array.isArray(m.content)) {
+      if (m.content.length === 0) return `messages[${i}].content array must be non-empty`;
+      // Element schema is intentionally not enforced — passed through to LLM as-is.
+    } else {
+      return `messages[${i}].content must be a non-empty string or a non-empty array`;
+    }
+  }
+  return null;
+}
+
 /**
  * Validate the schedule-message request payload.
  *
@@ -146,9 +180,40 @@ function validateScheduleMessagePayload(payload) {
     }
   }
 
+  // ─── Prompt schema (shared by prompted / auto / instant AI configs) ──
+  //
+  // Callers provide *exactly one of* `completePrompt` (string) or `messages`
+  // (OpenAI-style array). Same contract as @rei-standard/amsg-instant; the
+  // server's LLM path forwards either verbatim.
+  const promptCheck = (() => {
+    const hasCompletePrompt = payload.completePrompt !== undefined && payload.completePrompt !== null && payload.completePrompt !== '';
+    const hasMessages = payload.messages !== undefined && payload.messages !== null;
+    if (hasCompletePrompt && hasMessages) {
+      return {
+        error: { code: 'INVALID_PARAMETERS', message: 'exactly one of `completePrompt` or `messages` must be provided（两者不能同时出现）', details: { invalidFields: ['completePrompt', 'messages'] } },
+        hasCompletePrompt: true, hasMessages: true,
+      };
+    }
+    if (hasMessages) {
+      const err = validateLlmMessagesArray(payload.messages);
+      if (err) {
+        return {
+          error: { code: 'INVALID_PARAMETERS', message: err, details: { invalidFields: ['messages'] } },
+          hasCompletePrompt: false, hasMessages: true,
+        };
+      }
+    }
+    return { error: null, hasCompletePrompt, hasMessages };
+  })();
+
+  if (promptCheck.error) {
+    return { valid: false, errorCode: promptCheck.error.code, errorMessage: promptCheck.error.message, details: promptCheck.error.details };
+  }
+  const hasPrompt = promptCheck.hasCompletePrompt || promptCheck.hasMessages;
+
   if (payload.messageType === 'prompted' || payload.messageType === 'auto') {
     const missingAiFields = [];
-    if (!payload.completePrompt) missingAiFields.push('completePrompt');
+    if (!hasPrompt) missingAiFields.push('completePrompt or messages');
     if (!payload.apiUrl) missingAiFields.push('apiUrl');
     if (!payload.apiKey) missingAiFields.push('apiKey');
     if (!payload.primaryModel) missingAiFields.push('primaryModel');
@@ -161,13 +226,21 @@ function validateScheduleMessagePayload(payload) {
     if (payload.recurrenceType && payload.recurrenceType !== 'none') {
       return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: 'instant 类型的 recurrenceType 必须为 none', details: { invalidFields: ['recurrenceType (must be "none" for instant type)'] } };
     }
-    const hasAiConfig = payload.completePrompt && payload.apiUrl && payload.apiKey && payload.primaryModel;
+    const hasAiConfig = hasPrompt && payload.apiUrl && payload.apiKey && payload.primaryModel;
     const hasUserMessage = payload.userMessage;
     if (!hasAiConfig && !hasUserMessage) {
-      return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: 'instant 类型必须提供 userMessage 或完整的 AI 配置', details: { missingFields: ['userMessage or (completePrompt + apiUrl + apiKey + primaryModel)'] } };
+      return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: 'instant 类型必须提供 userMessage 或完整的 AI 配置', details: { missingFields: ['userMessage or ((completePrompt | messages) + apiUrl + apiKey + primaryModel)'] } };
     }
   }
 
+  if (
+    payload.temperature !== undefined &&
+    payload.temperature !== null &&
+    (typeof payload.temperature !== 'number' || !Number.isFinite(payload.temperature))
+  ) {
+    return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['temperature (must be a finite number)'] } };
+  }
+
   if (payload.avatarUrl && !isValidUrl(payload.avatarUrl)) {
     return { valid: false, errorCode: 'INVALID_PARAMETERS', errorMessage: '缺少必需参数或参数格式错误', details: { invalidFields: ['avatarUrl (invalid URL format)'] } };
   }
@@ -681,7 +754,8 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
       messageContent = decryptedPayload.userMessage;
 
     } else if (decryptedPayload.messageType === 'instant') {
-      if (decryptedPayload.completePrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
+      const hasPrompt = !!decryptedPayload.completePrompt || (Array.isArray(decryptedPayload.messages) && decryptedPayload.messages.length > 0);
+      if (hasPrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
         messageContent = await _callAI(decryptedPayload);
       } else if (decryptedPayload.userMessage) {
         messageContent = decryptedPayload.userMessage;
@@ -887,12 +961,29 @@ async function _callAI(payload) {
  * @returns {Object}
  */
 function buildAiRequestBody(payload) {
+  // messages mode (added in v2.2.0): forward the caller's OpenAI-style array
+  // verbatim — same contract as @rei-standard/amsg-instant 0.5.0+. No auto
+  // role injection, no concatenation back to a single user message. Lets
+  // the upstream app preserve system / multi-turn context byte-for-byte
+  // across the schedule-message path.
+  const llmMessages = Array.isArray(payload.messages) && payload.messages.length > 0
+    ? payload.messages
+    : [{ role: 'user', content: payload.completePrompt }];
+
   const requestBody = {
     model: payload.primaryModel,
-    messages: [{ role: 'user', content: payload.completePrompt }],
-    temperature: 0.8
+    messages: llmMessages,
   };
 
+  // Match the instant package's behavior: only inject default temperature
+  // for the legacy completePrompt path; messages mode forwards whatever the
+  // upstream app set (or nothing) so behavior matches their main chat path.
+  if (payload.temperature !== undefined && payload.temperature !== null) {
+    requestBody.temperature = payload.temperature;
+  } else if (!Array.isArray(payload.messages)) {
+    requestBody.temperature = 0.8;
+  }
+
   if (payload.maxTokens === undefined || payload.maxTokens === null) {
     return requestBody;
   }
@@ -906,12 +997,27 @@ function buildAiRequestBody(payload) {
 }
 
 /**
- * Normalize AI API URL with minimal, non-breaking rules:
- * - trim whitespace
- * - remove redundant trailing slashes from pathname
- * - keep query string untouched
+ * Normalize AI API URL for OpenAI-compatible chat endpoints.
+ *
+ * **Keep in sync** with `@rei-standard/amsg-instant`'s
+ * `src/message-processor.js` `normalizeAiApiUrl` — same rules, same
+ * tests. The two packages share this logic but each carry their own copy
+ * to avoid an architectural dependency (server should not depend on the
+ * stateless worker package).
  *
- * Note: This function does NOT auto-append /v1 or /chat/completions.
+ * Rules (idempotent — running it twice equals 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)                          → leave as-is. The caller
+ *     knows their own routing.
+ *
+ * Query string is preserved verbatim.
  *
  * @param {string} apiUrl
  * @returns {string}
@@ -920,7 +1026,8 @@ function normalizeAiApiUrl(apiUrl) {
   if (typeof apiUrl !== 'string' || !apiUrl.trim()) {
     throw new Error(
       'Invalid apiUrl: apiUrl is required. ' +
-      'Please provide a full chat endpoint URL (for example: https://api.openai.com/v1/chat/completions).'
+      'Please provide a chat endpoint URL ' +
+      '(for example: https://api.openai.com or https://api.openai.com/v1/chat/completions).'
     );
   }
 
@@ -931,12 +1038,23 @@ function normalizeAiApiUrl(apiUrl) {
     parsedUrl = new URL(trimmedApiUrl);
   } catch {
     throw new Error(
-      `Invalid apiUrl: "${apiUrl}". ` +
-      'Please provide a valid absolute URL that points to a full chat endpoint.'
+      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
     );
   }
 
-  parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, '') || '/';
+  let path = parsedUrl.pathname.replace(/\/+$/, '') || '/';
+
+  if (/\/chat\/completions$/.test(path)) ; else if (path === '/') {
+    // Bare host → assume OpenAI shape.
+    path = '/v1/chat/completions';
+  } else if (/\/v\d+$/.test(path)) {
+    // Path ends in `/v1`, `/v2`, … — caller already versioned the URL.
+    // Append only `/chat/completions`; never re-add `/v1`.
+    path = `${path}/chat/completions`;
+  }
+  // Any other custom path is left untouched on purpose.
+
+  parsedUrl.pathname = path;
   return parsedUrl.toString();
 }
 
@@ -1025,14 +1143,27 @@ function createScheduleMessageHandler(ctx) {
       apiUrl: payload.apiUrl || null,
       apiKey: payload.apiKey || null,
       primaryModel: payload.primaryModel || null,
+      // Prompt is one-of: legacy completePrompt (string) OR messages (OpenAI-
+      // style array). Validation has already enforced exactly-one-of, so
+      // exactly one of these will be non-null when an AI config is provided.
       completePrompt: payload.completePrompt || null,
+      messages: Array.isArray(payload.messages) ? payload.messages : null,
       maxTokens: payload.maxTokens ?? null,
+      temperature: payload.temperature ?? null,
       pushSubscription: payload.pushSubscription,
       metadata: payload.metadata || {}
     };
 
     const encryptedPayload = encryptForStorage(JSON.stringify(fullTaskData), userKey);
 
+    /**
+     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
+     *   This branch is kept for backward compatibility and the existing behavior
+     *   (create task → process → delete) is unchanged. The dedicated amsg-instant
+     *   package is stateless (no DB roundtrip), deployable to Cloudflare Workers,
+     *   and locks the encryption + push-payload contract behind a single version.
+     *   See packages/rei-standard-amsg/instant/README.md.
+     */
     // Instant type: check VAPID before creating the task to avoid orphaned rows
     if (payload.messageType === 'instant') {
       if (!ctx.vapid.email || !ctx.vapid.publicKey || !ctx.vapid.privateKey) {
@@ -1086,6 +1217,13 @@ function createScheduleMessageHandler(ctx) {
       return { status: 500, body: { success: false, error: { code: 'TASK_CREATE_FAILED', message: '创建任务失败' } } };
     }
 
+    /**
+     * @deprecated Soft-deprecated. For new code, use @rei-standard/amsg-instant.
+     *   The "create-task → process-by-uuid → delete-task" sequence below is
+     *   preserved verbatim so existing clients keep working. New integrations
+     *   should call the dedicated amsg-instant endpoint instead — it skips this
+     *   DB round-trip entirely. See packages/rei-standard-amsg/instant/README.md.
+     */
     // Instant type: send immediately
     if (payload.messageType === 'instant') {
       try {
@@ -1408,6 +1546,30 @@ function createUpdateMessageHandler(ctx) {
       return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: '更新数据格式错误', details: { invalidFields: ['maxTokens'] } } } };
     }
 
+    // Reject updates that try to set both completePrompt and messages at
+    // once. We don't enforce one-of-required here (callers may patch other
+    // fields), but the two prompt sources are mutually exclusive and must
+    // stay that way in storage too.
+    if (
+      updates.completePrompt &&
+      updates.messages !== undefined && updates.messages !== null
+    ) {
+      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: 'completePrompt 与 messages 不能同时更新（二选一）', details: { invalidFields: ['completePrompt', 'messages'] } } } };
+    }
+    if (updates.messages !== undefined && updates.messages !== null) {
+      const msgErr = validateLlmMessagesArray(updates.messages);
+      if (msgErr) {
+        return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: msgErr, details: { invalidFields: ['messages'] } } } };
+      }
+    }
+    if (
+      Object.prototype.hasOwnProperty.call(updates, 'temperature') &&
+      updates.temperature !== null &&
+      (typeof updates.temperature !== 'number' || !Number.isFinite(updates.temperature))
+    ) {
+      return { status: 400, body: { success: false, error: { code: 'INVALID_UPDATE_DATA', message: '更新数据格式错误', details: { invalidFields: ['temperature'] } } } };
+    }
+
     // Fetch existing task
     const existingTask = await db.getTaskByUuid(taskUuid, userId);
 
@@ -1421,14 +1583,27 @@ function createUpdateMessageHandler(ctx) {
 
     const existingData = JSON.parse(decryptFromStorage(existingTask.encrypted_payload, userKey));
 
+    // When the caller switches prompt source (completePrompt ↔ messages),
+    // null out the other so storage stays one-of (matches schedule-message
+    // shape and prevents buildAiRequestBody from accidentally seeing both).
+    const promptUpdates = {};
+    if (updates.completePrompt) {
+      promptUpdates.completePrompt = updates.completePrompt;
+      promptUpdates.messages = null;
+    } else if (updates.messages !== undefined && updates.messages !== null) {
+      promptUpdates.messages = updates.messages;
+      promptUpdates.completePrompt = null;
+    }
+
     const updatedData = {
       ...existingData,
-      ...(updates.completePrompt && { completePrompt: updates.completePrompt }),
+      ...promptUpdates,
       ...(updates.userMessage && { userMessage: updates.userMessage }),
       ...(updates.recurrenceType && { recurrenceType: updates.recurrenceType }),
       ...(updates.avatarUrl && { avatarUrl: updates.avatarUrl }),
       ...(updates.metadata && { metadata: updates.metadata }),
-      ...(Object.prototype.hasOwnProperty.call(updates, 'maxTokens') && { maxTokens: updates.maxTokens ?? null })
+      ...(Object.prototype.hasOwnProperty.call(updates, 'maxTokens') && { maxTokens: updates.maxTokens ?? null }),
+      ...(Object.prototype.hasOwnProperty.call(updates, 'temperature') && { temperature: updates.temperature ?? null })
     };
 
     const encryptedPayload = encryptForStorage(JSON.stringify(updatedData), userKey);
@@ -2162,4 +2337,4 @@ async function createReiServer(config) {
   };
 }
 
-export { createAdapter, createReiServer, createTenantToken, decryptFromStorage, decryptPayload, deriveUserEncryptionKey, encryptForStorage, isValidISO8601, isValidUUID, isValidUUIDv4, isValidUrl, validateScheduleMessagePayload, verifyTenantToken };
+export { createAdapter, createReiServer, createTenantToken, decryptFromStorage, decryptPayload, deriveUserEncryptionKey, encryptForStorage, isValidISO8601, isValidUUID, isValidUUIDv4, isValidUrl, validateLlmMessagesArray, validateScheduleMessagePayload, verifyTenantToken };

package/dist/index.mjs

@@ -47,6 +47,29 @@ function isValidUUIDv4(uuid) {
   const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
   return uuidV4Regex.test(uuid);
 }
+var VALID_LLM_MESSAGE_ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant", "tool"]);
+function validateLlmMessagesArray(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return "messages must be a non-empty array";
+  }
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (!m || typeof m !== "object" || Array.isArray(m)) {
+      return `messages[${i}] must be an object`;
+    }
+    if (!VALID_LLM_MESSAGE_ROLES.has(m.role)) {
+      return `messages[${i}].role must be one of system / user / assistant / tool`;
+    }
+    if (typeof m.content === "string") {
+      if (!m.content) return `messages[${i}].content must be a non-empty string`;
+    } else if (Array.isArray(m.content)) {
+      if (m.content.length === 0) return `messages[${i}].content array must be non-empty`;
+    } else {
+      return `messages[${i}].content must be a non-empty string or a non-empty array`;
+    }
+  }
+  return null;
+}
 function validateScheduleMessagePayload(payload) {
   if (!payload.contactName || typeof payload.contactName !== "string") {
     return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { missingFields: ["contactName"] } };
@@ -74,9 +97,35 @@ function validateScheduleMessagePayload(payload) {
       return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { missingFields: ["userMessage (required for fixed type)"] } };
     }
   }
+  const promptCheck = (() => {
+    const hasCompletePrompt = payload.completePrompt !== void 0 && payload.completePrompt !== null && payload.completePrompt !== "";
+    const hasMessages = payload.messages !== void 0 && payload.messages !== null;
+    if (hasCompletePrompt && hasMessages) {
+      return {
+        error: { code: "INVALID_PARAMETERS", message: "exactly one of `completePrompt` or `messages` must be provided\uFF08\u4E24\u8005\u4E0D\u80FD\u540C\u65F6\u51FA\u73B0\uFF09", details: { invalidFields: ["completePrompt", "messages"] } },
+        hasCompletePrompt: true,
+        hasMessages: true
+      };
+    }
+    if (hasMessages) {
+      const err = validateLlmMessagesArray(payload.messages);
+      if (err) {
+        return {
+          error: { code: "INVALID_PARAMETERS", message: err, details: { invalidFields: ["messages"] } },
+          hasCompletePrompt: false,
+          hasMessages: true
+        };
+      }
+    }
+    return { error: null, hasCompletePrompt, hasMessages };
+  })();
+  if (promptCheck.error) {
+    return { valid: false, errorCode: promptCheck.error.code, errorMessage: promptCheck.error.message, details: promptCheck.error.details };
+  }
+  const hasPrompt = promptCheck.hasCompletePrompt || promptCheck.hasMessages;
   if (payload.messageType === "prompted" || payload.messageType === "auto") {
     const missingAiFields = [];
-    if (!payload.completePrompt) missingAiFields.push("completePrompt");
+    if (!hasPrompt) missingAiFields.push("completePrompt or messages");
     if (!payload.apiUrl) missingAiFields.push("apiUrl");
     if (!payload.apiKey) missingAiFields.push("apiKey");
     if (!payload.primaryModel) missingAiFields.push("primaryModel");
@@ -88,12 +137,15 @@ function validateScheduleMessagePayload(payload) {
     if (payload.recurrenceType && payload.recurrenceType !== "none") {
       return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "instant \u7C7B\u578B\u7684 recurrenceType \u5FC5\u987B\u4E3A none", details: { invalidFields: ['recurrenceType (must be "none" for instant type)'] } };
     }
-    const hasAiConfig = payload.completePrompt && payload.apiUrl && payload.apiKey && payload.primaryModel;
+    const hasAiConfig = hasPrompt && payload.apiUrl && payload.apiKey && payload.primaryModel;
     const hasUserMessage = payload.userMessage;
     if (!hasAiConfig && !hasUserMessage) {
-      return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "instant \u7C7B\u578B\u5FC5\u987B\u63D0\u4F9B userMessage \u6216\u5B8C\u6574\u7684 AI \u914D\u7F6E", details: { missingFields: ["userMessage or (completePrompt + apiUrl + apiKey + primaryModel)"] } };
+      return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "instant \u7C7B\u578B\u5FC5\u987B\u63D0\u4F9B userMessage \u6216\u5B8C\u6574\u7684 AI \u914D\u7F6E", details: { missingFields: ["userMessage or ((completePrompt | messages) + apiUrl + apiKey + primaryModel)"] } };
     }
   }
+  if (payload.temperature !== void 0 && payload.temperature !== null && (typeof payload.temperature !== "number" || !Number.isFinite(payload.temperature))) {
+    return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["temperature (must be a finite number)"] } };
+  }
   if (payload.avatarUrl && !isValidUrl(payload.avatarUrl)) {
     return { valid: false, errorCode: "INVALID_PARAMETERS", errorMessage: "\u7F3A\u5C11\u5FC5\u9700\u53C2\u6570\u6216\u53C2\u6570\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["avatarUrl (invalid URL format)"] } };
   }
@@ -395,7 +447,8 @@ async function processSingleMessage(task, ctx, providedMasterKey) {
     if (decryptedPayload.messageType === "fixed") {
       messageContent = decryptedPayload.userMessage;
     } else if (decryptedPayload.messageType === "instant") {
-      if (decryptedPayload.completePrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
+      const hasPrompt = !!decryptedPayload.completePrompt || Array.isArray(decryptedPayload.messages) && decryptedPayload.messages.length > 0;
+      if (hasPrompt && decryptedPayload.apiUrl && decryptedPayload.apiKey && decryptedPayload.primaryModel) {
         messageContent = await _callAI(decryptedPayload);
       } else if (decryptedPayload.userMessage) {
         messageContent = decryptedPayload.userMessage;
@@ -537,11 +590,16 @@ async function _callAI(payload) {
   return content.trim();
 }
 function buildAiRequestBody(payload) {
+  const llmMessages = Array.isArray(payload.messages) && payload.messages.length > 0 ? payload.messages : [{ role: "user", content: payload.completePrompt }];
   const requestBody = {
     model: payload.primaryModel,
-    messages: [{ role: "user", content: payload.completePrompt }],
-    temperature: 0.8
+    messages: llmMessages
   };
+  if (payload.temperature !== void 0 && payload.temperature !== null) {
+    requestBody.temperature = payload.temperature;
+  } else if (!Array.isArray(payload.messages)) {
+    requestBody.temperature = 0.8;
+  }
   if (payload.maxTokens === void 0 || payload.maxTokens === null) {
     return requestBody;
   }
@@ -554,7 +612,7 @@ function buildAiRequestBody(payload) {
 function normalizeAiApiUrl(apiUrl) {
   if (typeof apiUrl !== "string" || !apiUrl.trim()) {
     throw new Error(
-      "Invalid apiUrl: apiUrl is required. Please provide a full chat endpoint URL (for example: https://api.openai.com/v1/chat/completions)."
+      "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)."
     );
   }
   const trimmedApiUrl = apiUrl.trim();
@@ -563,10 +621,17 @@ function normalizeAiApiUrl(apiUrl) {
     parsedUrl = new URL(trimmedApiUrl);
   } catch {
     throw new Error(
-      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL that points to a full chat endpoint.`
+      `Invalid apiUrl: "${apiUrl}". Please provide a valid absolute URL.`
     );
   }
-  parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, "") || "/";
+  let path = parsedUrl.pathname.replace(/\/+$/, "") || "/";
+  if (/\/chat\/completions$/.test(path)) {
+  } else if (path === "/") {
+    path = "/v1/chat/completions";
+  } else if (/\/v\d+$/.test(path)) {
+    path = `${path}/chat/completions`;
+  }
+  parsedUrl.pathname = path;
   return parsedUrl.toString();
 }
 
@@ -634,8 +699,13 @@ function createScheduleMessageHandler(ctx) {
       apiUrl: payload.apiUrl || null,
       apiKey: payload.apiKey || null,
       primaryModel: payload.primaryModel || null,
+      // Prompt is one-of: legacy completePrompt (string) OR messages (OpenAI-
+      // style array). Validation has already enforced exactly-one-of, so
+      // exactly one of these will be non-null when an AI config is provided.
       completePrompt: payload.completePrompt || null,
+      messages: Array.isArray(payload.messages) ? payload.messages : null,
       maxTokens: payload.maxTokens ?? null,
+      temperature: payload.temperature ?? null,
       pushSubscription: payload.pushSubscription,
       metadata: payload.metadata || {}
     };
@@ -947,6 +1017,18 @@ function createUpdateMessageHandler(ctx) {
     if (Object.prototype.hasOwnProperty.call(updates, "maxTokens") && updates.maxTokens !== null && (!Number.isInteger(updates.maxTokens) || updates.maxTokens <= 0)) {
       return { status: 400, body: { success: false, error: { code: "INVALID_UPDATE_DATA", message: "\u66F4\u65B0\u6570\u636E\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["maxTokens"] } } } };
     }
+    if (updates.completePrompt && updates.messages !== void 0 && updates.messages !== null) {
+      return { status: 400, body: { success: false, error: { code: "INVALID_UPDATE_DATA", message: "completePrompt \u4E0E messages \u4E0D\u80FD\u540C\u65F6\u66F4\u65B0\uFF08\u4E8C\u9009\u4E00\uFF09", details: { invalidFields: ["completePrompt", "messages"] } } } };
+    }
+    if (updates.messages !== void 0 && updates.messages !== null) {
+      const msgErr = validateLlmMessagesArray(updates.messages);
+      if (msgErr) {
+        return { status: 400, body: { success: false, error: { code: "INVALID_UPDATE_DATA", message: msgErr, details: { invalidFields: ["messages"] } } } };
+      }
+    }
+    if (Object.prototype.hasOwnProperty.call(updates, "temperature") && updates.temperature !== null && (typeof updates.temperature !== "number" || !Number.isFinite(updates.temperature))) {
+      return { status: 400, body: { success: false, error: { code: "INVALID_UPDATE_DATA", message: "\u66F4\u65B0\u6570\u636E\u683C\u5F0F\u9519\u8BEF", details: { invalidFields: ["temperature"] } } } };
+    }
     const existingTask = await db.getTaskByUuid(taskUuid, userId);
     if (!existingTask) {
       const taskStatus = await db.getTaskStatus(taskUuid, userId);
@@ -956,14 +1038,23 @@ function createUpdateMessageHandler(ctx) {
       return { status: 409, body: { success: false, error: { code: "TASK_ALREADY_COMPLETED", message: "\u4EFB\u52A1\u5DF2\u5B8C\u6210\u6216\u5DF2\u5931\u8D25\uFF0C\u65E0\u6CD5\u66F4\u65B0" } } };
     }
     const existingData = JSON.parse(decryptFromStorage(existingTask.encrypted_payload, userKey));
+    const promptUpdates = {};
+    if (updates.completePrompt) {
+      promptUpdates.completePrompt = updates.completePrompt;
+      promptUpdates.messages = null;
+    } else if (updates.messages !== void 0 && updates.messages !== null) {
+      promptUpdates.messages = updates.messages;
+      promptUpdates.completePrompt = null;
+    }
     const updatedData = {
       ...existingData,
-      ...updates.completePrompt && { completePrompt: updates.completePrompt },
+      ...promptUpdates,
       ...updates.userMessage && { userMessage: updates.userMessage },
       ...updates.recurrenceType && { recurrenceType: updates.recurrenceType },
       ...updates.avatarUrl && { avatarUrl: updates.avatarUrl },
       ...updates.metadata && { metadata: updates.metadata },
-      ...Object.prototype.hasOwnProperty.call(updates, "maxTokens") && { maxTokens: updates.maxTokens ?? null }
+      ...Object.prototype.hasOwnProperty.call(updates, "maxTokens") && { maxTokens: updates.maxTokens ?? null },
+      ...Object.prototype.hasOwnProperty.call(updates, "temperature") && { temperature: updates.temperature ?? null }
     };
     const encryptedPayload = encryptForStorage(JSON.stringify(updatedData), userKey);
     const extraFields = updates.nextSendAt ? { next_send_at: updates.nextSendAt } : void 0;
@@ -1484,6 +1575,7 @@ export {
   isValidUUID,
   isValidUUIDv4,
   isValidUrl,
+  validateLlmMessagesArray,
   validateScheduleMessagePayload,
   verifyTenantToken
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-server",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "ReiStandard Active Messaging server SDK with pluggable database adapters",
   "repository": {
     "type": "git",