@rei-standard/amsg-server 2.6.0-next.7 → 2.6.0-next.9

package/dist/{cloudflare-BBPmRS2L.d.cts → cloudflare-kUY6z-k5.d.cts}

@@ -777,6 +777,9 @@ async function callLlm(payload, options = {}) {
  * - 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 the
+ * caller passes a non-empty payload.tools.
+ *
  * @param {Object} payload
  * @returns {Object}
  */
@@ -804,6 +807,18 @@ function buildAiRequestBody(payload) {
     requestBody.temperature = 0.8;
   }
 
+  // tools mode (added in v2.6.0): forward the caller's OpenAI tools array
+  // verbatim — same philosophy as messages mode above. The agentic loop
+  // already appends assistant tool_calls + role:'tool' results; this is
+  // the request-side half of the same protocol. An empty array is treated
+  // as "no tools" because some OpenAI-compatible relays reject `tools: []`.
+  if (Array.isArray(payload.tools) && payload.tools.length > 0) {
+    requestBody.tools = payload.tools;
+    if (payload.toolChoice !== undefined && payload.toolChoice !== null) {
+      requestBody.tool_choice = payload.toolChoice;
+    }
+  }
+
   if (payload.maxTokens === undefined || payload.maxTokens === null) {
     return requestBody;
   }
@@ -1163,6 +1178,37 @@ async function writeClientStateEntries({ db, userId, userKey, entries }) {
  * 不用再自己维护 Map<sessionId, state>。fire 结束（finish / skip-push /
  * 抛错 / 轮数超限）后随调用栈丢弃；库不读不写、不落库、不打日志。
  *
+ * 工具声明：onBeforeFire 的返回值里可以带 `tools`（OpenAI 的 tools 数组，
+ * 另有可选的 `toolChoice`），本次 fire 的每一轮 LLM 请求都原样带上它们——
+ * 补完那轮模型仍可能再发起调用。库不看 tools 的内容，执行照旧是
+ * executeToolCalls 的事。
+ *
+ * 自排后续任务：fireCtx 和每轮的 sessionCtx 上都挂着 scheduleTask，宿主用它
+ * 在这次 fire 里给同一个用户再建一条定时任务（「这条发完，一个半小时后我再
+ * 接着说一句」）。写口在 sessionCtx 上也给，是因为要不要接着说往往是看完
+ * LLM 输出才定的，那时 onBeforeFire 早已返回。凭据（pushSubscription /
+ * apiKey）和投递配置从当前任务继承、宿主全程看不到（与 buildHookTask 屏蔽
+ * 凭据同一个原则），宿主只提供「什么时候、说什么方向」。
+ *
+ * 新任务不继承 completePrompt / messages，两者都置 null：fire-time hook 每次
+ * 现场重组 prompt，把排程时冻结的旧 prompt 带过去，会在新任务万一走回老链路
+ * （onBeforeFire 返回 null、或那次部署没配 hooks）时静默顶替宿主的意图——
+ * 与其发一条来路不明的旧文案，不如让它当场失败、走既有的重试/标记逻辑。
+ *
+ * 护栏（几条都是这个能力能不能上线的关键）：
+ *   - firstSendTime 至少比现在晚 MIN_SCHEDULE_LEAD_MS（60 秒）。cron 每分钟
+ *     一跳，排在 60 秒内等于让下一跳立刻捡走，容易变成自己触发自己的紧密循环。
+ *   - messageType 只收 auto / prompted / fixed，不收 instant。instant 的语义是
+ *     「建行的那一刻就投递」，那条路径归 POST /schedule-message 管；从 fire 里
+ *     造这么一行，投递时机反而说不清（这里不投，要等 cron 捞到才发）。
+ *   - 单次 fire 的建任务上限默认 DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE 条，
+ *     factory 配置 ctx.maxScheduledTasksPerFire 可覆盖（0 表示不许自排）。模型
+ *     自排后续本质上是个可以无限延伸的链：没有上限的话，一次 fire 里连排十条、
+ *     或者每条任务都排下一条，就成了谁也没按下停止键的循环。
+ *   - uuid 冲突不抛错，返回 { created: false, reason: 'duplicate' }。fire 失败
+ *     会整条重跑（run-tick 的重试语义），宿主传一个由「任务 id + 触发时刻」推
+ *     出来的确定性 uuid 就天然幂等，不会每重试一次多排一条。
+ *
  * Budget guards, both factory-level (ctx.maxToolIterations /
  * ctx.totalTimeoutMs) and per-fire (onBeforeFire may return
  * { messages, maxToolIterations?, totalTimeoutMs? } to override for one
@@ -1177,6 +1223,17 @@ async function writeClientStateEntries({ db, userId, userKey, entries }) {
 const DEFAULT_MAX_TOOL_ITERATIONS = 5;
 const DEFAULT_TOTAL_TIMEOUT_MS = 240_000;
 
+// 一次 fire 里最多能给自己排几条后续任务（ctx.maxScheduledTasksPerFire 可覆盖）。
+const DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE = 2;
+// 自排任务的最小提前量：cron 一分钟一跳，比这更近等于让下一跳立刻捡走。
+const MIN_SCHEDULE_LEAD_MS = 60_000;
+
+// 自排任务允许的类型。instant 归 POST /schedule-message 那条同步路径管。
+const SCHEDULABLE_MESSAGE_TYPES = new Set(['auto', 'prompted', 'fixed']);
+// 与 validateScheduleMessagePayload 同一套；run-tick 只认得这三种，别的值会让
+// 任务发完之后推进不到下一次。
+const SCHEDULABLE_RECURRENCE_TYPES = new Set(['none', 'daily', 'weekly']);
+
 // Same pacing as the legacy path / amsg-instant.
 const SLEEP_BETWEEN_MESSAGES_MS$1 = 1500;
 
@@ -1231,10 +1288,15 @@ function normalizeBeforeFireResult(result) {
       messages: result.messages,
       maxToolIterations: result.maxToolIterations,
       totalTimeoutMs: result.totalTimeoutMs,
+      // 归一成「有就是非空数组，否则 undefined」，让下面每轮的透传判断能直接
+      // 用真值。真正决定请求体带不带 tools 的规则住在 llm.js 的
+      // buildAiRequestBody（那边有测试钉着），这层只是不把空数组往下传。
+      tools: Array.isArray(result.tools) && result.tools.length > 0 ? result.tools : undefined,
+      toolChoice: result.toolChoice,
     };
   }
   throw new TypeError(
-    'AGENTIC_BAD_BEFORE_FIRE: onBeforeFire must return ChatMessage[] | { messages, maxToolIterations?, totalTimeoutMs? } | { skip: true } | null'
+    'AGENTIC_BAD_BEFORE_FIRE: onBeforeFire must return ChatMessage[] | { messages, maxToolIterations?, totalTimeoutMs?, tools?, toolChoice? } | { skip: true } | null'
   );
 }
 
@@ -1259,7 +1321,7 @@ function firstPositiveNumber(values, fallback) {
  * @param {import('../adapters/interface.js').TaskRow} args.task
  * @param {Object} args.decryptedPayload - decrypted task payload (has credentials; they stop here)
  * @param {string} args.userKey - per-user storage key (for readState decryption)
- * @param {Object} args.ctx - processor ctx ({ db, webpush, vapid, hooks, maxToolIterations, totalTimeoutMs })
+ * @param {Object} args.ctx - processor ctx ({ db, webpush, vapid, hooks, maxToolIterations, totalTimeoutMs, maxScheduledTasksPerFire })
  * @returns {Promise<{ handled: false } | { handled: true, result: { success: true, messagesSent: number, status: 'finished'|'skipped', iterations: number } }>}
  *   `handled: false` → caller falls back to the legacy frozen-prompt path
  *   (onBeforeFire returned null).
@@ -1378,6 +1440,174 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     return writeClientStateEntries({ db: ctx.db, userId: task.user_id, userKey, entries: normalized });
   };
 
+  const maxScheduledTasksPerFire =
+    Number.isInteger(ctx.maxScheduledTasksPerFire) && ctx.maxScheduledTasksPerFire >= 0
+      ? ctx.maxScheduledTasksPerFire
+      : DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE;
+  // 本次 fire 已经用掉的建任务额度。校验通过、真的要写库时才 +1，参数不合法的
+  // 调用不占额度；uuid 撞车（那条任务其实已经建出来了）照样占。
+  let scheduledTaskCount = 0;
+
+  /**
+   * scheduleTask(options) —— 在这次 fire 里给**同一个用户**再建一条定时任务。
+   *
+   * 典型用法：角色发完这条，想过一个半小时再接着说一句。以前只能写进
+   * client_state 等客户端上线重放，用户一直不上线这条链就断了；建成任务行之后，
+   * 到点由 cron 直接触发，跟别的定时消息一样。
+   *
+   * 凭据与投递配置（pushSubscription / apiUrl / apiKey / primaryModel /
+   * maxTokens / temperature / splitPattern）以及 contactName / avatarUrl /
+   * messageSubtype / userMessage 从当前任务继承，宿主只说「什么时候、说什么
+   * 方向」——hook 全程看不到凭据。completePrompt / messages 不继承（都置 null），
+   * 见文件头。
+   *
+   * @param {Object} options
+   * @param {string} options.firstSendTime      - 必填，ISO 8601；至少比现在晚 60 秒
+   * @param {'none'|'daily'|'weekly'} [options.recurrenceType='none']
+   * @param {'auto'|'prompted'|'fixed'} [options.messageType]  - 默认继承当前任务
+   * @param {Object} [options.metadata]         - 整体替换（不是深合并）当前任务的 metadata
+   * @param {string} [options.contactName]      - 默认继承
+   * @param {string|null} [options.avatarUrl]   - 默认继承
+   * @param {string} [options.messageSubtype]   - 默认继承
+   * @param {string|null} [options.userMessage] - 默认继承；messageType 'fixed' 时必须有
+   * @param {string} [options.uuid]             - 默认 randomUUID()；传确定性 uuid 可做重试幂等
+   * @returns {Promise<{ created: true, id: number|null, uuid: string, nextSendAt: string }
+   *   | { created: false, reason: 'duplicate', uuid: string }>}
+   */
+  const scheduleTask = async (options) => {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new TypeError('scheduleTask(options) 需要一个对象，至少包含 { firstSendTime }');
+    }
+
+    // ---- 触发时刻 ----
+    if (typeof options.firstSendTime !== 'string' || !options.firstSendTime.trim()) {
+      throw new RangeError('scheduleTask: firstSendTime 必填，且必须是 ISO 8601 字符串');
+    }
+    const firstSendAt = new Date(options.firstSendTime);
+    if (Number.isNaN(firstSendAt.getTime())) {
+      throw new RangeError(`scheduleTask: firstSendTime 解析不出合法时间：${options.firstSendTime}`);
+    }
+    const earliest = nowFn() + MIN_SCHEDULE_LEAD_MS;
+    if (firstSendAt.getTime() < earliest) {
+      throw new RangeError(
+        `scheduleTask: firstSendTime 至少要比现在晚 ${MIN_SCHEDULE_LEAD_MS / 1000} 秒` +
+        `（最早可排 ${new Date(earliest).toISOString()}，收到 ${firstSendAt.toISOString()}）` +
+        '——cron 一分钟一跳，排得更近等于让下一跳立刻捡走'
+      );
+    }
+    const nextSendAt = firstSendAt.toISOString();
+
+    // ---- 类型 ----
+    const inheritedType = options.messageType == null;
+    const messageType = inheritedType ? decryptedPayload.messageType : options.messageType;
+    if (messageType === 'instant') {
+      throw new TypeError(
+        "scheduleTask: messageType 不能是 'instant'——instant 的语义是「建行的那一刻就投递」，" +
+        '那条路径归 POST /schedule-message 管；从 fire 里建一条 instant，投递时机反而说不清。' +
+        (inheritedType ? '（这个 instant 是从当前任务继承来的，显式传 auto / prompted / fixed 覆盖它。）' : '')
+      );
+    }
+    if (!SCHEDULABLE_MESSAGE_TYPES.has(messageType)) {
+      throw new TypeError(
+        `scheduleTask: messageType 只能是 auto / prompted / fixed，收到 ${JSON.stringify(messageType)}`
+      );
+    }
+
+    const recurrenceType = options.recurrenceType == null ? 'none' : options.recurrenceType;
+    if (!SCHEDULABLE_RECURRENCE_TYPES.has(recurrenceType)) {
+      throw new TypeError(
+        `scheduleTask: recurrenceType 只能是 none / daily / weekly，收到 ${JSON.stringify(recurrenceType)}`
+      );
+    }
+
+    // ---- 继承 + 覆盖 ----
+    const contactName = options.contactName === undefined ? decryptedPayload.contactName : options.contactName;
+    if (typeof contactName !== 'string' || !contactName.trim()) {
+      throw new TypeError('scheduleTask: contactName 必须是非空字符串（默认继承当前任务）');
+    }
+    const userMessage = options.userMessage === undefined
+      ? (decryptedPayload.userMessage ?? null)
+      : options.userMessage;
+    if (messageType === 'fixed' && (typeof userMessage !== 'string' || !userMessage.trim())) {
+      throw new TypeError(
+        "scheduleTask: messageType 'fixed' 必须有 userMessage（自己传，或从当前任务继承到）" +
+        '——固定文本任务没有正文，就是一条永远发空的任务'
+      );
+    }
+    const metadata = options.metadata === undefined ? (decryptedPayload.metadata || {}) : options.metadata;
+    if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+      throw new TypeError('scheduleTask: metadata 必须是普通对象（整体替换当前任务的 metadata，不做深合并）');
+    }
+    const uuid = options.uuid == null ? randomUUID() : options.uuid;
+    if (typeof uuid !== 'string' || !uuid.trim()) {
+      throw new TypeError('scheduleTask: uuid 必须是非空字符串');
+    }
+
+    // ---- 额度 ----
+    if (scheduledTaskCount >= maxScheduledTasksPerFire) {
+      throw new RangeError(
+        `scheduleTask: 单次 fire 最多建 ${maxScheduledTasksPerFire} 条任务` +
+        `（factory 配置 maxScheduledTasksPerFire 可调），这是第 ${scheduledTaskCount + 1} 条`
+      );
+    }
+    // readState 在适配器不支持时降级成空数组；建任务不一样，静默成功会让宿主
+    // 以为后续那条已经排上了，其实谁也不会触发它。
+    if (!ctx.db || typeof ctx.db.createTask !== 'function') {
+      throw new Error('AGENTIC_SCHEDULE_UNSUPPORTED: 当前数据库适配器不支持建任务（缺 createTask）');
+    }
+    scheduledTaskCount++;
+
+    // 字段构成与 POST /schedule-message 落库的那份保持一致，只是走库内部、不经 HTTP。
+    const fullTaskData = {
+      contactName,
+      avatarUrl: options.avatarUrl === undefined ? (decryptedPayload.avatarUrl || null) : (options.avatarUrl || null),
+      messageType,
+      messageSubtype: (options.messageSubtype === undefined ? decryptedPayload.messageSubtype : options.messageSubtype) || 'chat',
+      userMessage: userMessage || null,
+      firstSendTime: nextSendAt,
+      recurrenceType,
+      apiUrl: decryptedPayload.apiUrl || null,
+      apiKey: decryptedPayload.apiKey || null,
+      primaryModel: decryptedPayload.primaryModel || null,
+      // 见文件头：fire-time hook 每次现场重组 prompt，旧 prompt 带过去只会在新
+      // 任务走回老链路时顶替宿主的意图。
+      completePrompt: null,
+      messages: null,
+      maxTokens: decryptedPayload.maxTokens ?? null,
+      temperature: decryptedPayload.temperature ?? null,
+      splitPattern: decryptedPayload.splitPattern ?? null,
+      pushSubscription: decryptedPayload.pushSubscription,
+      metadata,
+    };
+
+    const encryptedPayload = await encryptForStorage(JSON.stringify(fullTaskData), userKey);
+
+    let created;
+    try {
+      created = await ctx.db.createTask({
+        user_id: task.user_id,
+        uuid,
+        encrypted_payload: encryptedPayload,
+        next_send_at: nextSendAt,
+        message_type: messageType,
+      });
+    } catch (error) {
+      // 撞 uuid 不算错：fire 失败会整条重跑，宿主用确定性 uuid（任务 id + 触发
+      // 时刻推出来的那种）就天然幂等，重试不会多排一条。
+      if (isUniqueViolation(error)) return { created: false, reason: 'duplicate', uuid };
+      throw error;
+    }
+    if (!created) {
+      throw new Error('AGENTIC_SCHEDULE_FAILED: createTask 没有返回新建的任务行');
+    }
+    return {
+      created: true,
+      id: created.id ?? null,
+      uuid: created.uuid ?? uuid,
+      nextSendAt: created.next_send_at ?? nextSendAt,
+    };
+  };
+
   // 单次 fire 的宿主便签：onBeforeFire 的 fireCtx 和同一次 fire 每轮的
   // sessionCtx（onLLMOutput / executeToolCalls）拿到同一个对象引用，fire 结束
   // （finish / skip-push / 抛错 / 轮数超限）随调用栈丢弃。库自己不读不写、
@@ -1389,6 +1619,7 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     userId: task.user_id,
     readState,
     writeState,
+    scheduleTask,
     now: new Date(nowFn()),
     scratch,
   });
@@ -1430,16 +1661,21 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     // must not outlive totalTimeoutMs waiting for its own 300s abort.
     const roundTimeoutMs = Math.max(1, Math.min(300_000, deadline - nowFn()));
     const { response: llmResponse } = await callLlm(
-      { ...decryptedPayload, messages },
+      {
+        ...decryptedPayload,
+        messages,
+        ...(normalized.tools ? { tools: normalized.tools, toolChoice: normalized.toolChoice } : {}),
+      },
       { requireContent: false, timeoutMs: roundTimeoutMs }
     );
 
     const assistantMessage = extractAssistantMessage(llmResponse);
     messages = [...messages, assistantMessage];
 
-    // 共享的 SessionContext（与 amsg-instant 同形状）之上，再挂两个状态访问器：
-    // 大内容要不要旁路存，往往到工具跑完、组 push 时才知道，而那正是
-    // onLLMOutput / executeToolCalls 的位置，onBeforeFire 早就返回了。
+    // 共享的 SessionContext（与 amsg-instant 同形状）之上，再挂两个状态访问器
+    // 和 scheduleTask：大内容要不要旁路存、要不要给自己排条后续，往往到工具跑完、
+    // 组 push 时才知道，而那正是 onLLMOutput / executeToolCalls 的位置，
+    // onBeforeFire 早就返回了。
     const sessionCtx = Object.freeze({
       ...buildSessionContext({
         sessionId,
@@ -1454,6 +1690,7 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
       }),
       readState,
       writeState,
+      scheduleTask,
     });
 
     const decision = await hooks.onLLMOutput(sessionCtx);
@@ -1505,10 +1742,24 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
 
     // Text-protocol classifiers synthesize toolCalls the raw assistant
     // message doesn't carry; stamp them on so the appended role:'tool'
-    // results stay valid for OpenAI-compatible APIs.
-    const assistantWithTools = Array.isArray(assistantMessage.tool_calls) && assistantMessage.tool_calls.length > 0
+    // results stay valid for OpenAI-compatible APIs. Merge rather than pick
+    // one side: when a native tool_call and a synthesized one land in the
+    // same round, both need their id on the assistant turn, or the half
+    // that's missing leaves an orphan role:'tool' and a strict relay
+    // rejects the next round.
+    //
+    // Contract for onLLMOutput: the toolCalls it returns must cover every
+    // native tool_call the model declared. A native call left out still
+    // gets declared on the assistant turn (it came from the model) but has
+    // no matching role:'tool' result, and a strict relay rejects the next
+    // round over the unanswered id. Drop a call on purpose → return a
+    // result for it saying so, don't just omit it.
+    const nativeCalls = Array.isArray(assistantMessage.tool_calls) ? assistantMessage.tool_calls : [];
+    const nativeIds = new Set(nativeCalls.map((tc) => tc && tc.id));
+    const synthesized = toolCalls.filter((tc) => !nativeIds.has(tc && tc.id));
+    const assistantWithTools = synthesized.length === 0
       ? assistantMessage
-      : { ...assistantMessage, tool_calls: toolCalls };
+      : { ...assistantMessage, tool_calls: [...nativeCalls, ...synthesized] };
     messages = [...messages.slice(0, -1), assistantWithTools, ...toolResults];
   }
 
@@ -3539,6 +3790,8 @@ const SERVER_FEATURES = Object.freeze([
   'agentic-hooks',
   'agentic-scratch',
   'agentic-write-state',
+  'agentic-fire-tools',
+  'agentic-schedule-task',
   'vapid-public-key',
 ]);
 
@@ -3578,6 +3831,7 @@ function createCapabilitiesHandler(ctx) {
  * @param {number} [config.maxToolIterations] - factory default LLM-round cap for the agentic loop (default 5).
  * @param {number} [config.totalTimeoutMs] - factory default wall-time ceiling for the agentic loop (default 240000).
  * @param {number} [config.maxStateValueBytes] - client_state 单条 value 的总上限（默认 5MB）。超过 200KB 的值由服务端透明分块存储（见 lib/state-chunks.js）。
+ * @param {number} [config.maxScheduledTasksPerFire] - 一次 fire 里 hook 用 ctx.scheduleTask() 最多能建几条后续任务（默认 2，0 表示不许自排）。
  * @returns {{ handlers: Object, ctx: Object }}
  */
 
@@ -3607,7 +3861,9 @@ function createSingleUserServer(config) {
     hooks: config.hooks || null,
     maxToolIterations: config.maxToolIterations,
     totalTimeoutMs: config.totalTimeoutMs,
-    maxStateValueBytes: config.maxStateValueBytes
+    maxStateValueBytes: config.maxStateValueBytes,
+    // hook 的 ctx.scheduleTask() 单次 fire 建任务的条数上限（默认 2）。
+    maxScheduledTasksPerFire: config.maxScheduledTasksPerFire
   };
 
   return {
@@ -4044,10 +4300,11 @@ function createWebCryptoWebPush(vapid = {}, { ttl = SCHEDULED_DEFAULT_TTL } = {}
  * Access-Control-* on responses. With no `cors` the Worker stays same-origin.
  *
  * Fire-time hooks are opt-in too: pass `hooks: { onBeforeFire, onLLMOutput,
- * executeToolCalls }` (+ optional `maxToolIterations` / `totalTimeoutMs`) in the
- * config to let scheduled AI tasks assemble their prompt and run a server-side
- * tool loop at fire time. Omit them and AI tasks replay the schedule-time frozen
- * prompt exactly as before. See lib/agentic-fire.js.
+ * executeToolCalls }` (+ optional `maxToolIterations` / `totalTimeoutMs` /
+ * `maxScheduledTasksPerFire`) in the config to let scheduled AI tasks assemble
+ * their prompt and run a server-side tool loop at fire time. Omit them and AI
+ * tasks replay the schedule-time frozen prompt exactly as before. See
+ * lib/agentic-fire.js.
  *
  * scheduled() 每次触发都会先给任务占位（在行的 lease_until 上写租约），同一
  * 条任务不会被相邻两跳重复触发（见 lib/run-tick.js）。租期默认 10 分钟，可以
@@ -4187,6 +4444,8 @@ function createSingleUserCloudflareWorker(buildConfig) {
         totalTimeoutMs: cfg.totalTimeoutMs,
         // hook 的 ctx.writeState() 用它判断单条 value 的上限，和 PUT /client-state 同一个配置。
         maxStateValueBytes: cfg.maxStateValueBytes,
+        // hook 的 ctx.scheduleTask() 单次 fire 建任务的条数上限（默认 2）。
+        maxScheduledTasksPerFire: cfg.maxScheduledTasksPerFire,
         // 任务占位租期（默认 10 分钟，随 totalTimeoutMs 抬高）。
         claimLeaseMs: cfg.claimLeaseMs
       });