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

package/README.md

@@ -121,6 +121,51 @@ const { bytes, remainingBytes, withinLimit } = measurePushPayload(JSON.stringify
 
 装不下的内容（长文、附件详情）建议走旁路：正文存进 `client_state`，push 里只带一个引用键，客户端上线后用 `GET /client-state` 取回。单用户 Worker 的 fire-time hook 用 `ctx.writeState()` 写，见 [`examples/cloudflare-single-user/README.md`](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/server/examples/cloudflare-single-user/README.md)。
 
+## Fire 时刻 hooks
+
+配上 `hooks: { onBeforeFire, onLLMOutput, executeToolCalls }` 之后，AI 类任务的 prompt 不再是排程那一刻冻结的文本，而是 cron 触发时现场组装，工具也在服务端就地跑完，全程不需要客户端在线。完整用法见 [`examples/cloudflare-single-user/README.md`](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/server/examples/cloudflare-single-user/README.md) 的「Fire 时刻 hooks」。
+
+三个 hook 拿到的 ctx 上都有这几个口子：
+
+| ctx 上的口子 | 干什么 |
+|---|---|
+| `readState(ns)` / `writeState(ns, entries)` | 读写 `client_state`，和客户端 `GET/PUT /client-state` 是同一份数据 |
+| `scheduleTask(options)` | 给同一个用户再建一条定时任务 |
+| `scratch` | 本次 fire 的便签对象，三个 hook 共享同一个引用，fire 结束即丢弃 |
+
+### `ctx.scheduleTask(options)`
+
+角色在这次 fire 里给自己排一条后续任务：「这条发完，一个半小时后我再接着说一句」。建出来的是一条正常的任务行，到点由 cron 触发，用户全程离线也不影响。
+
+```js
+const result = await ctx.scheduleTask({
+  firstSendTime: new Date(Date.now() + 90 * 60_000).toISOString(), // 必填，ISO 字符串
+  messageType: 'auto',            // 可选，默认继承当前任务
+  recurrenceType: 'none',         // 可选，默认 none
+  metadata: { beat: 'followup' }, // 可选，整体替换当前任务的 metadata（不深合并）
+  uuid: `fire-${ctx.task.id}-${ctx.task.nextSendAt}`, // 可选，默认随机
+});
+// → { created: true, id, uuid, nextSendAt }
+//   或 { created: false, reason: 'duplicate', uuid }
+```
+
+凭据和投递配置（`pushSubscription` / `apiUrl` / `apiKey` / `primaryModel` / `maxTokens` / `temperature` / `splitPattern`）以及 `contactName` / `avatarUrl` / `messageSubtype` / `userMessage` 从当前任务继承，宿主只说「什么时候、说什么方向」——hook 全程看不到凭据。`completePrompt` / `messages` 不继承（都置 `null`）：hook 每次现场重组 prompt，把排程时冻结的旧 prompt 带过去，新任务万一走回冻结 prompt 老链路就会静默发出一条谁也没打算发的文案。
+
+护栏：
+
+| 护栏 | 阈值 / 规则 | 不满足时 | 为什么 |
+|---|---|---|---|
+| `firstSendTime` | 必填、能解析成合法时间、至少比现在晚 **60 秒** | `RangeError` | cron 一分钟一跳，排在 60 秒内等于让下一跳立刻捡走，容易变成自己触发自己的紧密循环 |
+| `messageType` | 只收 `auto` / `prompted` / `fixed` | `TypeError` | `instant` 的语义是「建行的那一刻就投递」，那条路径归 `POST /schedule-message` 管；从 fire 里造这么一行，投递时机反而说不清 |
+| `messageType: 'fixed'` | 必须有 `userMessage`（自己传或继承到） | `TypeError` | 固定文本任务没有正文，就是一条永远发空的任务 |
+| 单次 fire 的建任务条数 | 默认 **2 条**，factory 配置 `maxScheduledTasksPerFire` 可调（`0` = 不许自排） | `RangeError` | 模型自排后续本质上是条能无限延伸的链，没有上限就没人按停止键 |
+| `uuid` 撞车 | 不当错误处理 | 返回 `{ created: false, reason: 'duplicate', uuid }` | fire 失败会整条重跑，宿主传一个由「任务 id + 触发时刻」推出来的确定性 uuid 就天然幂等 |
+| 数据库适配器没有 `createTask` | — | 抛 `AGENTIC_SCHEDULE_UNSUPPORTED` | 静默成功会让宿主以为后续那条排上了，其实谁也不会触发它 |
+
+`recurrenceType` 沿用排程接口那套 `none` / `daily` / `weekly`，别的值抛 `TypeError`。参数不合法的调用不占建任务额度；uuid 撞车占（那条任务其实已经建出来了）。
+
+`GET /capabilities` 的 features 里有 `agentic-schedule-task`，前端可以据此判断部署的 worker 认不认这条链路。
+
 ## 导出（新增）
 
 - `validateLlmMessagesArray(messages)` — 同步预校验 messages 数组，返回 `string | null`（错误信息 / 通过）。和 `@rei-standard/amsg-instant` 的校验规则字节级一致。

package/dist/{chunk-YQPWXPIN.cjs → chunk-3QRVP4JE.cjs}

@@ -443,6 +443,12 @@ function buildAiRequestBody(payload) {
   } else if (!Array.isArray(payload.messages)) {
     requestBody.temperature = 0.8;
   }
+  if (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;
   }
@@ -635,6 +641,10 @@ async function writeClientStateEntries({ db, userId, userKey, entries }) {
 // src/server/lib/agentic-fire.js
 var DEFAULT_MAX_TOOL_ITERATIONS = 5;
 var DEFAULT_TOTAL_TIMEOUT_MS = 24e4;
+var DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE = 2;
+var MIN_SCHEDULE_LEAD_MS = 6e4;
+var SCHEDULABLE_MESSAGE_TYPES = /* @__PURE__ */ new Set(["auto", "prompted", "fixed"]);
+var SCHEDULABLE_RECURRENCE_TYPES = /* @__PURE__ */ new Set(["none", "daily", "weekly"]);
 var SLEEP_BETWEEN_MESSAGES_MS = 1500;
 var CREDENTIAL_PAYLOAD_KEYS = /* @__PURE__ */ new Set(["apiKey", "pushSubscription"]);
 var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -667,11 +677,16 @@ function normalizeBeforeFireResult(result) {
     return {
       messages: result.messages,
       maxToolIterations: result.maxToolIterations,
-      totalTimeoutMs: result.totalTimeoutMs
+      totalTimeoutMs: result.totalTimeoutMs,
+      // 归一成「有就是非空数组，否则 undefined」，让下面每轮的透传判断能直接
+      // 用真值。真正决定请求体带不带 tools 的规则住在 llm.js 的
+      // buildAiRequestBody（那边有测试钉着），这层只是不把空数组往下传。
+      tools: Array.isArray(result.tools) && result.tools.length > 0 ? result.tools : void 0,
+      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"
   );
 }
 function firstPositiveInt(values, fallback) {
@@ -757,12 +772,123 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     });
     return writeClientStateEntries({ db: ctx.db, userId: task.user_id, userKey, entries: normalized2 });
   };
+  const maxScheduledTasksPerFire = Number.isInteger(ctx.maxScheduledTasksPerFire) && ctx.maxScheduledTasksPerFire >= 0 ? ctx.maxScheduledTasksPerFire : DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE;
+  let scheduledTaskCount = 0;
+  const scheduleTask = async (options) => {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+      throw new TypeError("scheduleTask(options) \u9700\u8981\u4E00\u4E2A\u5BF9\u8C61\uFF0C\u81F3\u5C11\u5305\u542B { firstSendTime }");
+    }
+    if (typeof options.firstSendTime !== "string" || !options.firstSendTime.trim()) {
+      throw new RangeError("scheduleTask: firstSendTime \u5FC5\u586B\uFF0C\u4E14\u5FC5\u987B\u662F ISO 8601 \u5B57\u7B26\u4E32");
+    }
+    const firstSendAt = new Date(options.firstSendTime);
+    if (Number.isNaN(firstSendAt.getTime())) {
+      throw new RangeError(`scheduleTask: firstSendTime \u89E3\u6790\u4E0D\u51FA\u5408\u6CD5\u65F6\u95F4\uFF1A${options.firstSendTime}`);
+    }
+    const earliest = nowFn() + MIN_SCHEDULE_LEAD_MS;
+    if (firstSendAt.getTime() < earliest) {
+      throw new RangeError(
+        `scheduleTask: firstSendTime \u81F3\u5C11\u8981\u6BD4\u73B0\u5728\u665A ${MIN_SCHEDULE_LEAD_MS / 1e3} \u79D2\uFF08\u6700\u65E9\u53EF\u6392 ${new Date(earliest).toISOString()}\uFF0C\u6536\u5230 ${firstSendAt.toISOString()}\uFF09\u2014\u2014cron \u4E00\u5206\u949F\u4E00\u8DF3\uFF0C\u6392\u5F97\u66F4\u8FD1\u7B49\u4E8E\u8BA9\u4E0B\u4E00\u8DF3\u7ACB\u523B\u6361\u8D70`
+      );
+    }
+    const nextSendAt = firstSendAt.toISOString();
+    const inheritedType = options.messageType == null;
+    const messageType = inheritedType ? decryptedPayload.messageType : options.messageType;
+    if (messageType === "instant") {
+      throw new TypeError(
+        "scheduleTask: messageType \u4E0D\u80FD\u662F 'instant'\u2014\u2014instant \u7684\u8BED\u4E49\u662F\u300C\u5EFA\u884C\u7684\u90A3\u4E00\u523B\u5C31\u6295\u9012\u300D\uFF0C\u90A3\u6761\u8DEF\u5F84\u5F52 POST /schedule-message \u7BA1\uFF1B\u4ECE fire \u91CC\u5EFA\u4E00\u6761 instant\uFF0C\u6295\u9012\u65F6\u673A\u53CD\u800C\u8BF4\u4E0D\u6E05\u3002" + (inheritedType ? "\uFF08\u8FD9\u4E2A instant \u662F\u4ECE\u5F53\u524D\u4EFB\u52A1\u7EE7\u627F\u6765\u7684\uFF0C\u663E\u5F0F\u4F20 auto / prompted / fixed \u8986\u76D6\u5B83\u3002\uFF09" : "")
+      );
+    }
+    if (!SCHEDULABLE_MESSAGE_TYPES.has(messageType)) {
+      throw new TypeError(
+        `scheduleTask: messageType \u53EA\u80FD\u662F auto / prompted / fixed\uFF0C\u6536\u5230 ${JSON.stringify(messageType)}`
+      );
+    }
+    const recurrenceType = options.recurrenceType == null ? "none" : options.recurrenceType;
+    if (!SCHEDULABLE_RECURRENCE_TYPES.has(recurrenceType)) {
+      throw new TypeError(
+        `scheduleTask: recurrenceType \u53EA\u80FD\u662F none / daily / weekly\uFF0C\u6536\u5230 ${JSON.stringify(recurrenceType)}`
+      );
+    }
+    const contactName = options.contactName === void 0 ? decryptedPayload.contactName : options.contactName;
+    if (typeof contactName !== "string" || !contactName.trim()) {
+      throw new TypeError("scheduleTask: contactName \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32\uFF08\u9ED8\u8BA4\u7EE7\u627F\u5F53\u524D\u4EFB\u52A1\uFF09");
+    }
+    const userMessage = options.userMessage === void 0 ? _nullishCoalesce(decryptedPayload.userMessage, () => ( null)) : options.userMessage;
+    if (messageType === "fixed" && (typeof userMessage !== "string" || !userMessage.trim())) {
+      throw new TypeError(
+        "scheduleTask: messageType 'fixed' \u5FC5\u987B\u6709 userMessage\uFF08\u81EA\u5DF1\u4F20\uFF0C\u6216\u4ECE\u5F53\u524D\u4EFB\u52A1\u7EE7\u627F\u5230\uFF09\u2014\u2014\u56FA\u5B9A\u6587\u672C\u4EFB\u52A1\u6CA1\u6709\u6B63\u6587\uFF0C\u5C31\u662F\u4E00\u6761\u6C38\u8FDC\u53D1\u7A7A\u7684\u4EFB\u52A1"
+      );
+    }
+    const metadata = options.metadata === void 0 ? decryptedPayload.metadata || {} : options.metadata;
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+      throw new TypeError("scheduleTask: metadata \u5FC5\u987B\u662F\u666E\u901A\u5BF9\u8C61\uFF08\u6574\u4F53\u66FF\u6362\u5F53\u524D\u4EFB\u52A1\u7684 metadata\uFF0C\u4E0D\u505A\u6DF1\u5408\u5E76\uFF09");
+    }
+    const uuid = options.uuid == null ? randomUUID() : options.uuid;
+    if (typeof uuid !== "string" || !uuid.trim()) {
+      throw new TypeError("scheduleTask: uuid \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32");
+    }
+    if (scheduledTaskCount >= maxScheduledTasksPerFire) {
+      throw new RangeError(
+        `scheduleTask: \u5355\u6B21 fire \u6700\u591A\u5EFA ${maxScheduledTasksPerFire} \u6761\u4EFB\u52A1\uFF08factory \u914D\u7F6E maxScheduledTasksPerFire \u53EF\u8C03\uFF09\uFF0C\u8FD9\u662F\u7B2C ${scheduledTaskCount + 1} \u6761`
+      );
+    }
+    if (!ctx.db || typeof ctx.db.createTask !== "function") {
+      throw new Error("AGENTIC_SCHEDULE_UNSUPPORTED: \u5F53\u524D\u6570\u636E\u5E93\u9002\u914D\u5668\u4E0D\u652F\u6301\u5EFA\u4EFB\u52A1\uFF08\u7F3A createTask\uFF09");
+    }
+    scheduledTaskCount++;
+    const fullTaskData = {
+      contactName,
+      avatarUrl: options.avatarUrl === void 0 ? decryptedPayload.avatarUrl || null : options.avatarUrl || null,
+      messageType,
+      messageSubtype: (options.messageSubtype === void 0 ? 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: _nullishCoalesce(decryptedPayload.maxTokens, () => ( null)),
+      temperature: _nullishCoalesce(decryptedPayload.temperature, () => ( null)),
+      splitPattern: _nullishCoalesce(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) {
+      if (isUniqueViolation(error)) return { created: false, reason: "duplicate", uuid };
+      throw error;
+    }
+    if (!created) {
+      throw new Error("AGENTIC_SCHEDULE_FAILED: createTask \u6CA1\u6709\u8FD4\u56DE\u65B0\u5EFA\u7684\u4EFB\u52A1\u884C");
+    }
+    return {
+      created: true,
+      id: _nullishCoalesce(created.id, () => ( null)),
+      uuid: _nullishCoalesce(created.uuid, () => ( uuid)),
+      nextSendAt: _nullishCoalesce(created.next_send_at, () => ( nextSendAt))
+    };
+  };
   const scratch = {};
   const fireCtx = Object.freeze({
     task: buildHookTask(task, decryptedPayload),
     userId: task.user_id,
     readState,
     writeState,
+    scheduleTask,
     now: new Date(nowFn()),
     scratch
   });
@@ -789,7 +915,11 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     }
     const roundTimeoutMs = Math.max(1, Math.min(3e5, 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 = _amsgshared.extractAssistantMessage.call(void 0, llmResponse);
@@ -807,7 +937,8 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
         scratch
       }),
       readState,
-      writeState
+      writeState,
+      scheduleTask
     });
     const decision = await hooks.onLLMOutput(sessionCtx);
     _amsgshared.assertValidDecision.call(void 0, decision, { inlineToolCalls: true });
@@ -845,7 +976,10 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
         content: `Tool execution failed: ${_nullishCoalesce(_optionalChain([error, 'optionalAccess', _6 => _6.message]), () => ( String(error)))}`
       }));
     }
-    const assistantWithTools = Array.isArray(assistantMessage.tool_calls) && assistantMessage.tool_calls.length > 0 ? assistantMessage : { ...assistantMessage, tool_calls: toolCalls };
+    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: [...nativeCalls, ...synthesized] };
     messages = [...messages.slice(0, -1), assistantWithTools, ...toolResults];
   }
   throw new Error(`AGENTIC_LOOP_EXCEEDED: no finish/skip-push decision within ${maxToolIterations} LLM round(s)`);
@@ -2262,7 +2396,7 @@ function createClientStateHandler(ctx) {
 }
 
 // src/server/lib/version.js
-var SERVER_VERSION = true ? "2.6.0-next.7" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.6.0-next.9" : "0.0.0-dev";
 
 // src/server/handlers/capabilities.js
 var SERVER_FEATURES = Object.freeze([
@@ -2272,6 +2406,8 @@ var SERVER_FEATURES = Object.freeze([
   "agentic-hooks",
   "agentic-scratch",
   "agentic-write-state",
+  "agentic-fire-tools",
+  "agentic-schedule-task",
   "vapid-public-key"
 ]);
 function createCapabilitiesHandler(ctx) {
@@ -2313,7 +2449,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 {
     ctx,
@@ -2652,6 +2790,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
       });

package/dist/{chunk-I7EUMYQ4.mjs → chunk-S6O3MXQO.mjs}

@@ -443,6 +443,12 @@ function buildAiRequestBody(payload) {
   } else if (!Array.isArray(payload.messages)) {
     requestBody.temperature = 0.8;
   }
+  if (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;
   }
@@ -635,6 +641,10 @@ async function writeClientStateEntries({ db, userId, userKey, entries }) {
 // src/server/lib/agentic-fire.js
 var DEFAULT_MAX_TOOL_ITERATIONS = 5;
 var DEFAULT_TOTAL_TIMEOUT_MS = 24e4;
+var DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE = 2;
+var MIN_SCHEDULE_LEAD_MS = 6e4;
+var SCHEDULABLE_MESSAGE_TYPES = /* @__PURE__ */ new Set(["auto", "prompted", "fixed"]);
+var SCHEDULABLE_RECURRENCE_TYPES = /* @__PURE__ */ new Set(["none", "daily", "weekly"]);
 var SLEEP_BETWEEN_MESSAGES_MS = 1500;
 var CREDENTIAL_PAYLOAD_KEYS = /* @__PURE__ */ new Set(["apiKey", "pushSubscription"]);
 var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -667,11 +677,16 @@ function normalizeBeforeFireResult(result) {
     return {
       messages: result.messages,
       maxToolIterations: result.maxToolIterations,
-      totalTimeoutMs: result.totalTimeoutMs
+      totalTimeoutMs: result.totalTimeoutMs,
+      // 归一成「有就是非空数组，否则 undefined」，让下面每轮的透传判断能直接
+      // 用真值。真正决定请求体带不带 tools 的规则住在 llm.js 的
+      // buildAiRequestBody（那边有测试钉着），这层只是不把空数组往下传。
+      tools: Array.isArray(result.tools) && result.tools.length > 0 ? result.tools : void 0,
+      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"
   );
 }
 function firstPositiveInt(values, fallback) {
@@ -757,12 +772,123 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     });
     return writeClientStateEntries({ db: ctx.db, userId: task.user_id, userKey, entries: normalized2 });
   };
+  const maxScheduledTasksPerFire = Number.isInteger(ctx.maxScheduledTasksPerFire) && ctx.maxScheduledTasksPerFire >= 0 ? ctx.maxScheduledTasksPerFire : DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE;
+  let scheduledTaskCount = 0;
+  const scheduleTask = async (options) => {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+      throw new TypeError("scheduleTask(options) \u9700\u8981\u4E00\u4E2A\u5BF9\u8C61\uFF0C\u81F3\u5C11\u5305\u542B { firstSendTime }");
+    }
+    if (typeof options.firstSendTime !== "string" || !options.firstSendTime.trim()) {
+      throw new RangeError("scheduleTask: firstSendTime \u5FC5\u586B\uFF0C\u4E14\u5FC5\u987B\u662F ISO 8601 \u5B57\u7B26\u4E32");
+    }
+    const firstSendAt = new Date(options.firstSendTime);
+    if (Number.isNaN(firstSendAt.getTime())) {
+      throw new RangeError(`scheduleTask: firstSendTime \u89E3\u6790\u4E0D\u51FA\u5408\u6CD5\u65F6\u95F4\uFF1A${options.firstSendTime}`);
+    }
+    const earliest = nowFn() + MIN_SCHEDULE_LEAD_MS;
+    if (firstSendAt.getTime() < earliest) {
+      throw new RangeError(
+        `scheduleTask: firstSendTime \u81F3\u5C11\u8981\u6BD4\u73B0\u5728\u665A ${MIN_SCHEDULE_LEAD_MS / 1e3} \u79D2\uFF08\u6700\u65E9\u53EF\u6392 ${new Date(earliest).toISOString()}\uFF0C\u6536\u5230 ${firstSendAt.toISOString()}\uFF09\u2014\u2014cron \u4E00\u5206\u949F\u4E00\u8DF3\uFF0C\u6392\u5F97\u66F4\u8FD1\u7B49\u4E8E\u8BA9\u4E0B\u4E00\u8DF3\u7ACB\u523B\u6361\u8D70`
+      );
+    }
+    const nextSendAt = firstSendAt.toISOString();
+    const inheritedType = options.messageType == null;
+    const messageType = inheritedType ? decryptedPayload.messageType : options.messageType;
+    if (messageType === "instant") {
+      throw new TypeError(
+        "scheduleTask: messageType \u4E0D\u80FD\u662F 'instant'\u2014\u2014instant \u7684\u8BED\u4E49\u662F\u300C\u5EFA\u884C\u7684\u90A3\u4E00\u523B\u5C31\u6295\u9012\u300D\uFF0C\u90A3\u6761\u8DEF\u5F84\u5F52 POST /schedule-message \u7BA1\uFF1B\u4ECE fire \u91CC\u5EFA\u4E00\u6761 instant\uFF0C\u6295\u9012\u65F6\u673A\u53CD\u800C\u8BF4\u4E0D\u6E05\u3002" + (inheritedType ? "\uFF08\u8FD9\u4E2A instant \u662F\u4ECE\u5F53\u524D\u4EFB\u52A1\u7EE7\u627F\u6765\u7684\uFF0C\u663E\u5F0F\u4F20 auto / prompted / fixed \u8986\u76D6\u5B83\u3002\uFF09" : "")
+      );
+    }
+    if (!SCHEDULABLE_MESSAGE_TYPES.has(messageType)) {
+      throw new TypeError(
+        `scheduleTask: messageType \u53EA\u80FD\u662F auto / prompted / fixed\uFF0C\u6536\u5230 ${JSON.stringify(messageType)}`
+      );
+    }
+    const recurrenceType = options.recurrenceType == null ? "none" : options.recurrenceType;
+    if (!SCHEDULABLE_RECURRENCE_TYPES.has(recurrenceType)) {
+      throw new TypeError(
+        `scheduleTask: recurrenceType \u53EA\u80FD\u662F none / daily / weekly\uFF0C\u6536\u5230 ${JSON.stringify(recurrenceType)}`
+      );
+    }
+    const contactName = options.contactName === void 0 ? decryptedPayload.contactName : options.contactName;
+    if (typeof contactName !== "string" || !contactName.trim()) {
+      throw new TypeError("scheduleTask: contactName \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32\uFF08\u9ED8\u8BA4\u7EE7\u627F\u5F53\u524D\u4EFB\u52A1\uFF09");
+    }
+    const userMessage = options.userMessage === void 0 ? decryptedPayload.userMessage ?? null : options.userMessage;
+    if (messageType === "fixed" && (typeof userMessage !== "string" || !userMessage.trim())) {
+      throw new TypeError(
+        "scheduleTask: messageType 'fixed' \u5FC5\u987B\u6709 userMessage\uFF08\u81EA\u5DF1\u4F20\uFF0C\u6216\u4ECE\u5F53\u524D\u4EFB\u52A1\u7EE7\u627F\u5230\uFF09\u2014\u2014\u56FA\u5B9A\u6587\u672C\u4EFB\u52A1\u6CA1\u6709\u6B63\u6587\uFF0C\u5C31\u662F\u4E00\u6761\u6C38\u8FDC\u53D1\u7A7A\u7684\u4EFB\u52A1"
+      );
+    }
+    const metadata = options.metadata === void 0 ? decryptedPayload.metadata || {} : options.metadata;
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+      throw new TypeError("scheduleTask: metadata \u5FC5\u987B\u662F\u666E\u901A\u5BF9\u8C61\uFF08\u6574\u4F53\u66FF\u6362\u5F53\u524D\u4EFB\u52A1\u7684 metadata\uFF0C\u4E0D\u505A\u6DF1\u5408\u5E76\uFF09");
+    }
+    const uuid = options.uuid == null ? randomUUID() : options.uuid;
+    if (typeof uuid !== "string" || !uuid.trim()) {
+      throw new TypeError("scheduleTask: uuid \u5FC5\u987B\u662F\u975E\u7A7A\u5B57\u7B26\u4E32");
+    }
+    if (scheduledTaskCount >= maxScheduledTasksPerFire) {
+      throw new RangeError(
+        `scheduleTask: \u5355\u6B21 fire \u6700\u591A\u5EFA ${maxScheduledTasksPerFire} \u6761\u4EFB\u52A1\uFF08factory \u914D\u7F6E maxScheduledTasksPerFire \u53EF\u8C03\uFF09\uFF0C\u8FD9\u662F\u7B2C ${scheduledTaskCount + 1} \u6761`
+      );
+    }
+    if (!ctx.db || typeof ctx.db.createTask !== "function") {
+      throw new Error("AGENTIC_SCHEDULE_UNSUPPORTED: \u5F53\u524D\u6570\u636E\u5E93\u9002\u914D\u5668\u4E0D\u652F\u6301\u5EFA\u4EFB\u52A1\uFF08\u7F3A createTask\uFF09");
+    }
+    scheduledTaskCount++;
+    const fullTaskData = {
+      contactName,
+      avatarUrl: options.avatarUrl === void 0 ? decryptedPayload.avatarUrl || null : options.avatarUrl || null,
+      messageType,
+      messageSubtype: (options.messageSubtype === void 0 ? 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) {
+      if (isUniqueViolation(error)) return { created: false, reason: "duplicate", uuid };
+      throw error;
+    }
+    if (!created) {
+      throw new Error("AGENTIC_SCHEDULE_FAILED: createTask \u6CA1\u6709\u8FD4\u56DE\u65B0\u5EFA\u7684\u4EFB\u52A1\u884C");
+    }
+    return {
+      created: true,
+      id: created.id ?? null,
+      uuid: created.uuid ?? uuid,
+      nextSendAt: created.next_send_at ?? nextSendAt
+    };
+  };
   const scratch = {};
   const fireCtx = Object.freeze({
     task: buildHookTask(task, decryptedPayload),
     userId: task.user_id,
     readState,
     writeState,
+    scheduleTask,
     now: new Date(nowFn()),
     scratch
   });
@@ -789,7 +915,11 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     }
     const roundTimeoutMs = Math.max(1, Math.min(3e5, 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);
@@ -807,7 +937,8 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
         scratch
       }),
       readState,
-      writeState
+      writeState,
+      scheduleTask
     });
     const decision = await hooks.onLLMOutput(sessionCtx);
     assertValidDecision(decision, { inlineToolCalls: true });
@@ -845,7 +976,10 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
         content: `Tool execution failed: ${error?.message ?? String(error)}`
       }));
     }
-    const assistantWithTools = Array.isArray(assistantMessage.tool_calls) && assistantMessage.tool_calls.length > 0 ? assistantMessage : { ...assistantMessage, tool_calls: toolCalls };
+    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: [...nativeCalls, ...synthesized] };
     messages = [...messages.slice(0, -1), assistantWithTools, ...toolResults];
   }
   throw new Error(`AGENTIC_LOOP_EXCEEDED: no finish/skip-push decision within ${maxToolIterations} LLM round(s)`);
@@ -2262,7 +2396,7 @@ function createClientStateHandler(ctx) {
 }
 
 // src/server/lib/version.js
-var SERVER_VERSION = true ? "2.6.0-next.7" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.6.0-next.9" : "0.0.0-dev";
 
 // src/server/handlers/capabilities.js
 var SERVER_FEATURES = Object.freeze([
@@ -2272,6 +2406,8 @@ var SERVER_FEATURES = Object.freeze([
   "agentic-hooks",
   "agentic-scratch",
   "agentic-write-state",
+  "agentic-fire-tools",
+  "agentic-schedule-task",
   "vapid-public-key"
 ]);
 function createCapabilitiesHandler(ctx) {
@@ -2313,7 +2449,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 {
     ctx,
@@ -2652,6 +2790,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
       });