@rei-standard/amsg-server 2.6.0-next.8 → 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-HQHRXSQA.cjs → chunk-3QRVP4JE.cjs}

@@ -641,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));
@@ -674,6 +678,9 @@ 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 : void 0,
       toolChoice: result.toolChoice
     };
@@ -765,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
   });
@@ -819,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 });
@@ -2277,7 +2396,7 @@ function createClientStateHandler(ctx) {
 }
 
 // src/server/lib/version.js
-var SERVER_VERSION = true ? "2.6.0-next.8" : "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([
@@ -2288,6 +2407,7 @@ var SERVER_FEATURES = Object.freeze([
   "agentic-scratch",
   "agentic-write-state",
   "agentic-fire-tools",
+  "agentic-schedule-task",
   "vapid-public-key"
 ]);
 function createCapabilitiesHandler(ctx) {
@@ -2329,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,
@@ -2668,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-LEE5KQ7Y.mjs → chunk-S6O3MXQO.mjs}

@@ -641,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));
@@ -674,6 +678,9 @@ 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 : void 0,
       toolChoice: result.toolChoice
     };
@@ -765,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
   });
@@ -819,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 });
@@ -2277,7 +2396,7 @@ function createClientStateHandler(ctx) {
 }
 
 // src/server/lib/version.js
-var SERVER_VERSION = true ? "2.6.0-next.8" : "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([
@@ -2288,6 +2407,7 @@ var SERVER_FEATURES = Object.freeze([
   "agentic-scratch",
   "agentic-write-state",
   "agentic-fire-tools",
+  "agentic-schedule-task",
   "vapid-public-key"
 ]);
 function createCapabilitiesHandler(ctx) {
@@ -2329,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,
@@ -2668,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/{cloudflare-CH3dBl5b.d.cts → cloudflare-kUY6z-k5.d.cts}

@@ -1183,6 +1183,32 @@ async function writeClientStateEntries({ db, userId, userKey, entries }) {
  * 补完那轮模型仍可能再发起调用。库不看 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
@@ -1197,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;
 
@@ -1251,6 +1288,9 @@ 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,
     };
@@ -1281,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).
@@ -1400,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 / 抛错 / 轮数超限）随调用栈丢弃。库自己不读不写、
@@ -1411,6 +1619,7 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     userId: task.user_id,
     readState,
     writeState,
+    scheduleTask,
     now: new Date(nowFn()),
     scratch,
   });
@@ -1463,9 +1672,10 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     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,
@@ -1480,6 +1690,7 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
       }),
       readState,
       writeState,
+      scheduleTask,
     });
 
     const decision = await hooks.onLLMOutput(sessionCtx);
@@ -1536,6 +1747,13 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     // 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));
@@ -3573,6 +3791,7 @@ const SERVER_FEATURES = Object.freeze([
   'agentic-scratch',
   'agentic-write-state',
   'agentic-fire-tools',
+  'agentic-schedule-task',
   'vapid-public-key',
 ]);
 
@@ -3612,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 }}
  */
 
@@ -3641,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 {
@@ -4078,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 分钟，可以
@@ -4221,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
       });

package/dist/{cloudflare-CH3dBl5b.d.ts → cloudflare-kUY6z-k5.d.ts}

@@ -1183,6 +1183,32 @@ async function writeClientStateEntries({ db, userId, userKey, entries }) {
  * 补完那轮模型仍可能再发起调用。库不看 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
@@ -1197,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;
 
@@ -1251,6 +1288,9 @@ 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,
     };
@@ -1281,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).
@@ -1400,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 / 抛错 / 轮数超限）随调用栈丢弃。库自己不读不写、
@@ -1411,6 +1619,7 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     userId: task.user_id,
     readState,
     writeState,
+    scheduleTask,
     now: new Date(nowFn()),
     scratch,
   });
@@ -1463,9 +1672,10 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     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,
@@ -1480,6 +1690,7 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
       }),
       readState,
       writeState,
+      scheduleTask,
     });
 
     const decision = await hooks.onLLMOutput(sessionCtx);
@@ -1536,6 +1747,13 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
     // 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));
@@ -3573,6 +3791,7 @@ const SERVER_FEATURES = Object.freeze([
   'agentic-scratch',
   'agentic-write-state',
   'agentic-fire-tools',
+  'agentic-schedule-task',
   'vapid-public-key',
 ]);
 
@@ -3612,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 }}
  */
 
@@ -3641,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 {
@@ -4078,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 分钟，可以
@@ -4221,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
       });

package/dist/cloudflare.cjs

@@ -12,7 +12,7 @@
 
 
 
-var _chunkHQHRXSQAcjs = require('./chunk-HQHRXSQA.cjs');
+var _chunk3QRVP4JEcjs = require('./chunk-3QRVP4JE.cjs');
 
 
 
@@ -27,4 +27,4 @@ var _chunkHQHRXSQAcjs = require('./chunk-HQHRXSQA.cjs');
 
 
 
-exports.MAX_PUSH_PAYLOAD_BYTES = _chunkHQHRXSQAcjs.MAX_PUSH_PAYLOAD_BYTES; exports.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = _chunkHQHRXSQAcjs.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES; exports.WEB_PUSH_MAX_BODY_BYTES = _chunkHQHRXSQAcjs.WEB_PUSH_MAX_BODY_BYTES; exports.createD1Adapter = _chunkHQHRXSQAcjs.createD1Adapter; exports.createSingleUserCloudflareWorker = _chunkHQHRXSQAcjs.createSingleUserCloudflareWorker; exports.createSingleUserServer = _chunkHQHRXSQAcjs.createSingleUserServer; exports.createWebCryptoWebPush = _chunkHQHRXSQAcjs.createWebCryptoWebPush; exports.decryptFromStorage = _chunkHQHRXSQAcjs.decryptFromStorage; exports.decryptPayload = _chunkHQHRXSQAcjs.decryptPayload; exports.deriveUserEncryptionKey = _chunkHQHRXSQAcjs.deriveUserEncryptionKey; exports.encryptForStorage = _chunkHQHRXSQAcjs.encryptForStorage; exports.measurePushPayload = _chunkHQHRXSQAcjs.measurePushPayload; exports.runScheduledTick = _chunkHQHRXSQAcjs.runScheduledTick;
+exports.MAX_PUSH_PAYLOAD_BYTES = _chunk3QRVP4JEcjs.MAX_PUSH_PAYLOAD_BYTES; exports.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = _chunk3QRVP4JEcjs.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES; exports.WEB_PUSH_MAX_BODY_BYTES = _chunk3QRVP4JEcjs.WEB_PUSH_MAX_BODY_BYTES; exports.createD1Adapter = _chunk3QRVP4JEcjs.createD1Adapter; exports.createSingleUserCloudflareWorker = _chunk3QRVP4JEcjs.createSingleUserCloudflareWorker; exports.createSingleUserServer = _chunk3QRVP4JEcjs.createSingleUserServer; exports.createWebCryptoWebPush = _chunk3QRVP4JEcjs.createWebCryptoWebPush; exports.decryptFromStorage = _chunk3QRVP4JEcjs.decryptFromStorage; exports.decryptPayload = _chunk3QRVP4JEcjs.decryptPayload; exports.deriveUserEncryptionKey = _chunk3QRVP4JEcjs.deriveUserEncryptionKey; exports.encryptForStorage = _chunk3QRVP4JEcjs.encryptForStorage; exports.measurePushPayload = _chunk3QRVP4JEcjs.measurePushPayload; exports.runScheduledTick = _chunk3QRVP4JEcjs.runScheduledTick;

package/dist/cloudflare.d.cts

@@ -1,2 +1,2 @@
-export { M as MAX_PUSH_PAYLOAD_BYTES, W as WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES, f as WEB_PUSH_MAX_BODY_BYTES, h as createD1Adapter, j as createSingleUserCloudflareWorker, k as createSingleUserServer, l as createWebCryptoWebPush, m as decryptFromStorage, n as decryptPayload, o as deriveUserEncryptionKey, q as encryptForStorage, v as measurePushPayload, r as runScheduledTick } from './cloudflare-CH3dBl5b.cjs';
+export { M as MAX_PUSH_PAYLOAD_BYTES, W as WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES, f as WEB_PUSH_MAX_BODY_BYTES, h as createD1Adapter, j as createSingleUserCloudflareWorker, k as createSingleUserServer, l as createWebCryptoWebPush, m as decryptFromStorage, n as decryptPayload, o as deriveUserEncryptionKey, q as encryptForStorage, v as measurePushPayload, r as runScheduledTick } from './cloudflare-kUY6z-k5.cjs';
 import '@rei-standard/amsg-shared';

package/dist/cloudflare.d.ts

@@ -1,2 +1,2 @@
-export { M as MAX_PUSH_PAYLOAD_BYTES, W as WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES, f as WEB_PUSH_MAX_BODY_BYTES, h as createD1Adapter, j as createSingleUserCloudflareWorker, k as createSingleUserServer, l as createWebCryptoWebPush, m as decryptFromStorage, n as decryptPayload, o as deriveUserEncryptionKey, q as encryptForStorage, v as measurePushPayload, r as runScheduledTick } from './cloudflare-CH3dBl5b.js';
+export { M as MAX_PUSH_PAYLOAD_BYTES, W as WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES, f as WEB_PUSH_MAX_BODY_BYTES, h as createD1Adapter, j as createSingleUserCloudflareWorker, k as createSingleUserServer, l as createWebCryptoWebPush, m as decryptFromStorage, n as decryptPayload, o as deriveUserEncryptionKey, q as encryptForStorage, v as measurePushPayload, r as runScheduledTick } from './cloudflare-kUY6z-k5.js';
 import '@rei-standard/amsg-shared';

package/dist/cloudflare.mjs

@@ -12,7 +12,7 @@ import {
   encryptForStorage,
   measurePushPayload,
   runScheduledTick
-} from "./chunk-LEE5KQ7Y.mjs";
+} from "./chunk-S6O3MXQO.mjs";
 export {
   MAX_PUSH_PAYLOAD_BYTES,
   WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES,

package/dist/index.cjs

@@ -27,7 +27,7 @@
 
 
 
-var _chunkHQHRXSQAcjs = require('./chunk-HQHRXSQA.cjs');
+var _chunk3QRVP4JEcjs = require('./chunk-3QRVP4JE.cjs');
 
 // src/server/adapters/factory.js
 async function createAdapter(config) {
@@ -60,7 +60,7 @@ async function createAdapter(config) {
 // src/server/handlers/init-tenant.js
 function createInitTenantHandler(ctx) {
   async function POST(headers, body) {
-    const initSecret = _chunkHQHRXSQAcjs.getHeader.call(void 0, headers, "x-init-secret");
+    const initSecret = _chunk3QRVP4JEcjs.getHeader.call(void 0, headers, "x-init-secret");
     if (ctx.tenant.initSecret && initSecret !== ctx.tenant.initSecret) {
       return {
         status: 401,
@@ -73,7 +73,7 @@ function createInitTenantHandler(ctx) {
         }
       };
     }
-    const parsed = _chunkHQHRXSQAcjs.parseJsonBody.call(void 0, body);
+    const parsed = _chunk3QRVP4JEcjs.parseJsonBody.call(void 0, body);
     if (!parsed.ok) {
       return {
         status: 400,
@@ -87,7 +87,7 @@ function createInitTenantHandler(ctx) {
     const tenantId = payload.tenantId || void 0;
     const driver = payload.driver;
     const databaseUrl = payload.databaseUrl || payload.connectionString;
-    if (tenantId && !_chunkHQHRXSQAcjs.isValidUUIDv4.call(void 0, tenantId)) {
+    if (tenantId && !_chunk3QRVP4JEcjs.isValidUUIDv4.call(void 0, tenantId)) {
       return {
         status: 400,
         body: {
@@ -207,7 +207,7 @@ function createSendNotificationsHandler(ctx) {
         }
       };
     }
-    const data = await _chunkHQHRXSQAcjs.runScheduledTick.call(void 0, { ...ctx, db, masterKey });
+    const data = await _chunk3QRVP4JEcjs.runScheduledTick.call(void 0, { ...ctx, db, masterKey });
     return { status: 200, body: { success: true, data } };
   }
   return { POST };
@@ -579,12 +579,12 @@ async function createReiServer(config) {
   return {
     handlers: {
       initTenant: createInitTenantHandler(ctx),
-      getUserKey: _chunkHQHRXSQAcjs.createGetUserKeyHandler.call(void 0, ctx),
-      scheduleMessage: _chunkHQHRXSQAcjs.createScheduleMessageHandler.call(void 0, ctx),
+      getUserKey: _chunk3QRVP4JEcjs.createGetUserKeyHandler.call(void 0, ctx),
+      scheduleMessage: _chunk3QRVP4JEcjs.createScheduleMessageHandler.call(void 0, ctx),
       sendNotifications: createSendNotificationsHandler(ctx),
-      updateMessage: _chunkHQHRXSQAcjs.createUpdateMessageHandler.call(void 0, ctx),
-      cancelMessage: _chunkHQHRXSQAcjs.createCancelMessageHandler.call(void 0, ctx),
-      messages: _chunkHQHRXSQAcjs.createMessagesHandler.call(void 0, ctx)
+      updateMessage: _chunk3QRVP4JEcjs.createUpdateMessageHandler.call(void 0, ctx),
+      cancelMessage: _chunk3QRVP4JEcjs.createCancelMessageHandler.call(void 0, ctx),
+      messages: _chunk3QRVP4JEcjs.createMessagesHandler.call(void 0, ctx)
     }
   };
 }
@@ -614,4 +614,4 @@ async function createReiServer(config) {
 
 
 
-exports.MAX_PUSH_PAYLOAD_BYTES = _chunkHQHRXSQAcjs.MAX_PUSH_PAYLOAD_BYTES; exports.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = _chunkHQHRXSQAcjs.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES; exports.WEB_PUSH_MAX_BODY_BYTES = _chunkHQHRXSQAcjs.WEB_PUSH_MAX_BODY_BYTES; exports.createAdapter = createAdapter; exports.createD1Adapter = _chunkHQHRXSQAcjs.createD1Adapter; exports.createReiServer = createReiServer; exports.createSingleUserCloudflareWorker = _chunkHQHRXSQAcjs.createSingleUserCloudflareWorker; exports.createSingleUserServer = _chunkHQHRXSQAcjs.createSingleUserServer; exports.createTenantToken = createTenantToken; exports.createWebCryptoWebPush = _chunkHQHRXSQAcjs.createWebCryptoWebPush; exports.decryptFromStorage = _chunkHQHRXSQAcjs.decryptFromStorage; exports.decryptPayload = _chunkHQHRXSQAcjs.decryptPayload; exports.deriveUserEncryptionKey = _chunkHQHRXSQAcjs.deriveUserEncryptionKey; exports.encryptForStorage = _chunkHQHRXSQAcjs.encryptForStorage; exports.isValidISO8601 = _chunkHQHRXSQAcjs.isValidISO8601; exports.isValidUUID = _chunkHQHRXSQAcjs.isValidUUID; exports.isValidUUIDv4 = _chunkHQHRXSQAcjs.isValidUUIDv4; exports.isValidUrl = _chunkHQHRXSQAcjs.isValidUrl; exports.measurePushPayload = _chunkHQHRXSQAcjs.measurePushPayload; exports.runScheduledTick = _chunkHQHRXSQAcjs.runScheduledTick; exports.validateAvatarUrl = _chunkHQHRXSQAcjs.validateAvatarUrl; exports.validateLlmMessagesArray = _chunkHQHRXSQAcjs.validateLlmMessagesArray; exports.validateScheduleMessagePayload = _chunkHQHRXSQAcjs.validateScheduleMessagePayload; exports.validateSplitPattern = _chunkHQHRXSQAcjs.validateSplitPattern; exports.verifyTenantToken = verifyTenantToken;
+exports.MAX_PUSH_PAYLOAD_BYTES = _chunk3QRVP4JEcjs.MAX_PUSH_PAYLOAD_BYTES; exports.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = _chunk3QRVP4JEcjs.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES; exports.WEB_PUSH_MAX_BODY_BYTES = _chunk3QRVP4JEcjs.WEB_PUSH_MAX_BODY_BYTES; exports.createAdapter = createAdapter; exports.createD1Adapter = _chunk3QRVP4JEcjs.createD1Adapter; exports.createReiServer = createReiServer; exports.createSingleUserCloudflareWorker = _chunk3QRVP4JEcjs.createSingleUserCloudflareWorker; exports.createSingleUserServer = _chunk3QRVP4JEcjs.createSingleUserServer; exports.createTenantToken = createTenantToken; exports.createWebCryptoWebPush = _chunk3QRVP4JEcjs.createWebCryptoWebPush; exports.decryptFromStorage = _chunk3QRVP4JEcjs.decryptFromStorage; exports.decryptPayload = _chunk3QRVP4JEcjs.decryptPayload; exports.deriveUserEncryptionKey = _chunk3QRVP4JEcjs.deriveUserEncryptionKey; exports.encryptForStorage = _chunk3QRVP4JEcjs.encryptForStorage; exports.isValidISO8601 = _chunk3QRVP4JEcjs.isValidISO8601; exports.isValidUUID = _chunk3QRVP4JEcjs.isValidUUID; exports.isValidUUIDv4 = _chunk3QRVP4JEcjs.isValidUUIDv4; exports.isValidUrl = _chunk3QRVP4JEcjs.isValidUrl; exports.measurePushPayload = _chunk3QRVP4JEcjs.measurePushPayload; exports.runScheduledTick = _chunk3QRVP4JEcjs.runScheduledTick; exports.validateAvatarUrl = _chunk3QRVP4JEcjs.validateAvatarUrl; exports.validateLlmMessagesArray = _chunk3QRVP4JEcjs.validateLlmMessagesArray; exports.validateScheduleMessagePayload = _chunk3QRVP4JEcjs.validateScheduleMessagePayload; exports.validateSplitPattern = _chunk3QRVP4JEcjs.validateSplitPattern; exports.verifyTenantToken = verifyTenantToken;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { g as getHeader, p as parseJsonBody, i as isValidUUIDv4, r as runScheduledTick, c as createMessagesHandler, a as createCancelMessageHandler, b as createUpdateMessageHandler, d as createScheduleMessageHandler, e as createGetUserKeyHandler } from './cloudflare-CH3dBl5b.cjs';
-export { M as MAX_PUSH_PAYLOAD_BYTES, W as WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES, f as WEB_PUSH_MAX_BODY_BYTES, h as createD1Adapter, j as createSingleUserCloudflareWorker, k as createSingleUserServer, l as createWebCryptoWebPush, m as decryptFromStorage, n as decryptPayload, o as deriveUserEncryptionKey, q as encryptForStorage, s as isValidISO8601, t as isValidUUID, u as isValidUrl, v as measurePushPayload, w as validateLlmMessagesArray, x as validateScheduleMessagePayload, y as validateSplitPattern } from './cloudflare-CH3dBl5b.cjs';
+import { g as getHeader, p as parseJsonBody, i as isValidUUIDv4, r as runScheduledTick, c as createMessagesHandler, a as createCancelMessageHandler, b as createUpdateMessageHandler, d as createScheduleMessageHandler, e as createGetUserKeyHandler } from './cloudflare-kUY6z-k5.cjs';
+export { M as MAX_PUSH_PAYLOAD_BYTES, W as WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES, f as WEB_PUSH_MAX_BODY_BYTES, h as createD1Adapter, j as createSingleUserCloudflareWorker, k as createSingleUserServer, l as createWebCryptoWebPush, m as decryptFromStorage, n as decryptPayload, o as deriveUserEncryptionKey, q as encryptForStorage, s as isValidISO8601, t as isValidUUID, u as isValidUrl, v as measurePushPayload, w as validateLlmMessagesArray, x as validateScheduleMessagePayload, y as validateSplitPattern } from './cloudflare-kUY6z-k5.cjs';
 import { createHash, randomBytes, createCipheriv, createDecipheriv, timingSafeEqual, createHmac, randomUUID } from 'crypto';
 import { normalizeVapidSubject } from '@rei-standard/amsg-shared';
 export { validateAvatarUrl } from '@rei-standard/amsg-shared';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { g as getHeader, p as parseJsonBody, i as isValidUUIDv4, r as runScheduledTick, c as createMessagesHandler, a as createCancelMessageHandler, b as createUpdateMessageHandler, d as createScheduleMessageHandler, e as createGetUserKeyHandler } from './cloudflare-CH3dBl5b.js';
-export { M as MAX_PUSH_PAYLOAD_BYTES, W as WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES, f as WEB_PUSH_MAX_BODY_BYTES, h as createD1Adapter, j as createSingleUserCloudflareWorker, k as createSingleUserServer, l as createWebCryptoWebPush, m as decryptFromStorage, n as decryptPayload, o as deriveUserEncryptionKey, q as encryptForStorage, s as isValidISO8601, t as isValidUUID, u as isValidUrl, v as measurePushPayload, w as validateLlmMessagesArray, x as validateScheduleMessagePayload, y as validateSplitPattern } from './cloudflare-CH3dBl5b.js';
+import { g as getHeader, p as parseJsonBody, i as isValidUUIDv4, r as runScheduledTick, c as createMessagesHandler, a as createCancelMessageHandler, b as createUpdateMessageHandler, d as createScheduleMessageHandler, e as createGetUserKeyHandler } from './cloudflare-kUY6z-k5.js';
+export { M as MAX_PUSH_PAYLOAD_BYTES, W as WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES, f as WEB_PUSH_MAX_BODY_BYTES, h as createD1Adapter, j as createSingleUserCloudflareWorker, k as createSingleUserServer, l as createWebCryptoWebPush, m as decryptFromStorage, n as decryptPayload, o as deriveUserEncryptionKey, q as encryptForStorage, s as isValidISO8601, t as isValidUUID, u as isValidUrl, v as measurePushPayload, w as validateLlmMessagesArray, x as validateScheduleMessagePayload, y as validateSplitPattern } from './cloudflare-kUY6z-k5.js';
 import { createHash, randomBytes, createCipheriv, createDecipheriv, timingSafeEqual, createHmac, randomUUID } from 'crypto';
 import { normalizeVapidSubject } from '@rei-standard/amsg-shared';
 export { validateAvatarUrl } from '@rei-standard/amsg-shared';

package/dist/index.mjs

@@ -27,7 +27,7 @@ import {
   validateLlmMessagesArray,
   validateScheduleMessagePayload,
   validateSplitPattern
-} from "./chunk-LEE5KQ7Y.mjs";
+} from "./chunk-S6O3MXQO.mjs";
 
 // src/server/adapters/factory.js
 async function createAdapter(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-server",
-  "version": "2.6.0-next.8",
+  "version": "2.6.0-next.9",
   "description": "ReiStandard Active Messaging server SDK with pluggable database adapters. Three-axis push schema (messageKind / messageType / messageSubtype) from @rei-standard/amsg-shared. Auto-emits ReasoningPush when the LLM response carries reasoning_content.",
   "repository": {
     "type": "git",