@rei-standard/amsg-server 2.6.0-next.32 → 2.6.0-next.33

package/README.md

@@ -364,6 +364,16 @@ hook 在 `pushPayloads` 里自己写了这几个字段的话会被库覆盖：
 
 配上 `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」。
 
+`onBeforeFire` 的返回值决定这次触发怎么走：
+
+| 返回值 | 这次触发怎么走 |
+|---|---|
+| 消息数组，或 `{ messages, maxToolIterations?, totalTimeoutMs?, tools?, toolChoice? }` | 用这份 prompt 生成 |
+| `{ skip: true }` | 这次不发，按零推送的成功收场：一次性任务删掉、循环任务推进到下一次 |
+| `{ defer: { afterMs } }` | 现在不合适，`afterMs` 毫秒后再来问。见下面[推迟这次触发](#推迟这次触发defer) |
+| `null` | 交还给排程时冻结的 prompt |
+| 抛错 | 按投递失败处理：占一次重试、写 `last_error`、2 / 4 / 6 分钟退避 |
+
 三个 hook 拿到的 ctx 上都有这几个口子：
 
 | ctx 上的口子 | 干什么 |
@@ -383,6 +393,41 @@ hook 在 `pushPayloads` 里自己写了这几个字段的话会被库覆盖：
 
 `sessionId` 是给日志和去重用的不透明字符串，格式随版本变，别拆它拿上面这些值。
 
+### 推迟这次触发（defer）
+
+任务到点了，但宿主这会儿不方便生成——比如同一段对话里正有另一轮回复在生成，想等它结束再说。`onBeforeFire` 返回 `{ defer: { afterMs } }`：
+
+```js
+async onBeforeFire(ctx) {
+  if (await isConversationBusy(ctx)) return { defer: { afterMs: 30_000 } };
+  return buildMessages(ctx);
+}
+```
+
+这一次不调 LLM、不推送，也不调 `onLLMOutput` / `onAfterSend`。任务行上只有两处变化：`retry_after` 写成现在 + `afterMs`，租约放掉。到点之后 cron 把它重新捞起来，从 `onBeforeFire` 再走一遍，那时可以继续推迟。
+
+跟抛错重试的区别：
+
+| | 抛错 | `{ defer }` |
+|---|---|---|
+| `retry_count` | 加一，用完就终审 | 不变 |
+| `last_error` | 写上这次的原因 | 不写，也不清已有的 |
+| 多久之后再来 | 固定 2 / 4 / 6 分钟 | 宿主给的 `afterMs` |
+| `onFireSettled` 的 `status` | `failed` | `deferred`，带 `retryAfter` |
+
+两边相同的是 `next_send_at` 都不动：它一直是这次触发的名义时刻，`ctx.task.nextSendAt`、`occurrenceMs`、推送的 `messageId` 在推迟前后都是同一套。循环任务被推迟时不会推进到下一次。
+
+几条规矩：
+
+- `afterMs` 必须是有限正数，最大 24 小时（导出为 `MAX_DEFER_AFTER_MS`）。不合法的值按 hook 契约违约处理（`AGENTIC_BAD_BEFORE_FIRE`，一跳终审）。没有下限，但 cron 一分钟一跳，实际是「到点之后的第一跳」才会再问；用 `runTask` 自己触发的话，到点之前调它会得到 `retry_pending`。
+- 推迟不会让任务永远挂着。名义时刻过去超过 `staleAfterMs`（默认 60 分钟）的任务照常按过期处理：一次性任务标 `failed`、循环任务快进到下一次，并调 `onStaleSkip`。某次推迟的唤醒时刻已经越过这条线时，库不再等那一轮，当场按过期收场——这时宿主会先收到 `status: 'deferred'` 的 `onFireSettled`，紧接着收到 `onStaleSkip`。
+- 每次被重新问到都是一次新的 fire：`scratch` 是新的，`onFireSettled` 各调各的。
+- 只有定时投递（`runScheduledTick`、单用户 Worker 的 `scheduled()`、`runTask`）支持推迟，并且适配器要实现 `claimTask`（任务表有 `retry_after` 列，内置适配器都有）。`messageType: 'instant'` 在请求里当场投递的任务、以及没实现 `claimTask` 的自定义适配器返回 `{ defer }` 会得到 `AGENTIC_DEFER_UNSUPPORTED`，按[部署配错了算可重试](#部署配错了算可重试)处理。
+- 内容已经落进收件箱、只是推送没发完的重试不调 `onBeforeFire`（见[生成成功之后推送失败：只补推送](#生成成功之后推送失败只补推送)），那一跳也就不会被推迟。
+- 配了 `serializeBy` 时，被推迟的任务不占着分组：同组里排在它后面的任务可以先跑。
+
+tick 汇总的 `details.deferredTasks`（`{ taskId, retryAfter }`）列出这一跳被推迟的任务，它们不计入 `successCount` / `failedCount`。`GET /capabilities` 的 features 里有 `before-fire-defer`。
+
 ### config 级 hook
 
 这两个挂在 worker 工厂 config 的顶层（不在 `hooks` 里）：
@@ -390,7 +435,7 @@ hook 在 `pushPayloads` 里自己写了这几个字段的话会被库覆盖：
 | hook | 什么时候调 | 载荷 |
 |---|---|---|
 | `onAfterSend` | fire 的 pushPayloads 逐段发完，或中途发挂 | `{ task, sentCount, pushedCount, total, error, usage, usageTotal, llmCalls, outboxed, scratch, readState, writeState, emitResult }` |
-| `onFireSettled` | 一次 fire 收尾——只要 `onBeforeFire` 被调用过，什么结局都调一次 | `{ task, status, skipReason, sentCount, pushedCount, total, iterations, error, metadata, usage, usageTotal, llmCalls, outboxed, scratch, readState, writeState, emitResult }` |
+| `onFireSettled` | 一次 fire 收尾——只要 `onBeforeFire` 被调用过，什么结局都调一次 | `{ task, status, skipReason, retryAfter, sentCount, pushedCount, total, iterations, error, metadata, usage, usageTotal, llmCalls, outboxed, scratch, readState, writeState, emitResult }` |
 | `onStaleSkip` | 任务错过触发时刻超过 60 分钟、这一次（或这几次）不再补发 | `{ reason, action, metadata, recurrenceType, occurrenceMs, skippedCount, skippedOccurrences, skippedTruncated, nextSendAt, readState, writeState, emitResult }` |
 
 三个 hook 都自带 `readState` / `writeState` / `emitResult`，作用于当前用户，语义与 fire 级那套一致。`onStaleSkip` 尤其需要：服务停摆恢复后的第一跳里可能一次 fire 都没跑过，而那正是它要留痕迹的时候。
@@ -405,7 +450,9 @@ hook 在 `pushPayloads` 里自己写了这几个字段的话会被库覆盖：
 |---|---|
 | `sent` | pushPayloads 全部发完（`sentCount === total`） |
 | `skipped` | 这次不发。`skipReason` 区分是 `onBeforeFire` 直接 `{ skip: true }`（`'before-fire'`）还是模型跑完后判定不发（`'skip-push'`） |
+| `deferred` | `onBeforeFire` 返回了 `{ defer: { afterMs } }`：这次没生成也没发，任务还在。`retryAfter`（ISO 时刻）之后会从 `onBeforeFire` 重新走一遍；这个字段在其余结局都是 `null` |
 | `failed` | 链路抛错，`error` 带原始错误。发到第 k 段挂了也是这个：`sentCount = k`、`total` 是原本要发的段数 |
+| `cancelled` | 任务在投递期间被取消或顶替，见[取消正在执行的任务](#取消正在执行的生成与工具) |
 | `not-handled` | `onBeforeFire` 返回 `null`，这条任务交还给排程时冻结的 prompt 老链路。那条链路不归 fire hook 管，它后面发没发出去不体现在这里 |
 
 **用量记账**看这三个字段，两个 hook 都带，`onFireSettled` 的每种结局（发完、跳过、失败）都带——失败也花了钱：
@@ -507,7 +554,7 @@ const { messageId, pushed } = await ctx.emitResult({
 
 ### hook 契约违约算确定性失败
 
-宿主 hook 返回了库不认的东西（`onBeforeFire` 的返回形状、`onLLMOutput` 的决策标签），或者建后续任务时 `createTask` 没把行交回来——这些错误带 `permanent: true` 和一个稳定的 `code`（`AGENTIC_BAD_BEFORE_FIRE` / `AGENTIC_BAD_DECISION` / `AGENTIC_SCHEDULE_FAILED` / `TASK_PAYLOAD_TOO_LARGE`），投递侧据此跳过退避阶梯：一次性任务直接标 `failed`，循环任务作废本次 occurrence。重试也是同一个结果，而每重试一轮都要把 `onBeforeFire` 和一整轮 LLM 重跑一遍。
+宿主 hook 返回了库不认的东西（`onBeforeFire` 的返回形状、`{ defer }` 里不合法的 `afterMs`、`onLLMOutput` 的决策标签），或者建后续任务时 `createTask` 没把行交回来——这些错误带 `permanent: true` 和一个稳定的 `code`（`AGENTIC_BAD_BEFORE_FIRE` / `AGENTIC_BAD_DECISION` / `AGENTIC_SCHEDULE_FAILED` / `TASK_PAYLOAD_TOO_LARGE`），投递侧据此跳过退避阶梯：一次性任务直接标 `failed`，循环任务作废本次 occurrence。重试也是同一个结果，而每重试一轮都要把 `onBeforeFire` 和一整轮 LLM 重跑一遍。
 
 分界线是「谁写错了」：契约由宿主代码定死，重掷一次还是同一个形状；而模型这一轮掷出了什么则是每轮都可能不同的。所以「tool-request 决策里没有能解析的 `toolCalls`」（`AGENTIC_EMPTY_TOOL_REQUEST`）和「轮数用尽也没等到 `finish` / `skip-push`」（`AGENTIC_LOOP_EXCEEDED`）带 `code` 但不带 `permanent`，留在退避阶梯上——隔两分钟重掷一次多半就正常收尾了，判终态的话一次性任务第一次掷歪就永久 `failed`，行离开 `pending` 之后连 `PUT /update-message` 都救不回来（回 409）。
 

package/dist/{chunk-KZT3YC62.cjs → chunk-AM2MMY46.cjs}

@@ -1636,6 +1636,7 @@ 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 MAX_DEFER_AFTER_MS = 24 * 60 * 60 * 1e3;
 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;
@@ -1670,6 +1671,22 @@ function buildHookTask(task, decryptedPayload) {
     retryCount: _nullishCoalesce(task.retry_count, () => ( 0))
   });
 }
+var BAD_BEFORE_FIRE_MESSAGE = "AGENTIC_BAD_BEFORE_FIRE: onBeforeFire must return ChatMessage[] | { messages, maxToolIterations?, totalTimeoutMs?, tools?, toolChoice? } | { skip: true } | { defer: { afterMs } } | null";
+function readDeferAfterMs(defer) {
+  const afterMs = defer && typeof defer === "object" ? (
+    /** @type {any} */
+    defer.afterMs
+  ) : void 0;
+  if (typeof afterMs !== "number" || !Number.isFinite(afterMs) || afterMs <= 0 || afterMs > MAX_DEFER_AFTER_MS) {
+    throw markPermanent(
+      new TypeError(
+        `${BAD_BEFORE_FIRE_MESSAGE}\uFF08defer.afterMs \u5FC5\u987B\u662F\u6709\u9650\u6B63\u6570\uFF0C\u4E14\u4E0D\u8D85\u8FC7 ${MAX_DEFER_AFTER_MS} \u6BEB\u79D2\uFF09`
+      ),
+      "AGENTIC_BAD_BEFORE_FIRE"
+    );
+  }
+  return afterMs;
+}
 function normalizeBeforeFireResult(result) {
   if (Array.isArray(result)) {
     return { messages: result };
@@ -1686,12 +1703,7 @@ function normalizeBeforeFireResult(result) {
       toolChoice: result.toolChoice
     };
   }
-  throw markPermanent(
-    new TypeError(
-      "AGENTIC_BAD_BEFORE_FIRE: onBeforeFire must return ChatMessage[] | { messages, maxToolIterations?, totalTimeoutMs?, tools?, toolChoice? } | { skip: true } | null"
-    ),
-    "AGENTIC_BAD_BEFORE_FIRE"
-  );
+  throw markPermanent(new TypeError(BAD_BEFORE_FIRE_MESSAGE), "AGENTIC_BAD_BEFORE_FIRE");
 }
 function firstPositiveInt(values, fallback) {
   for (const v of values) {
@@ -2026,6 +2038,7 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
   };
   let settledStatus = "failed";
   let settledError = null;
+  let settledRetryAfter = null;
   try {
     const outcome = await runFireChain({
       task,
@@ -2050,7 +2063,11 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
       occurrenceMs
     });
     throwIfCancelled();
-    settledStatus = !outcome.handled ? "not-handled" : outcome.result.status === "skipped" ? "skipped" : "sent";
+    if (!outcome.handled) settledStatus = "not-handled";
+    else if (outcome.result.status === "deferred") {
+      settledStatus = "deferred";
+      settledRetryAfter = outcome.result.retryAfter;
+    } else settledStatus = outcome.result.status === "skipped" ? "skipped" : "sent";
     return outcome;
   } catch (error) {
     if (isCancelled() && !isTaskCancelledError(error)) {
@@ -2070,6 +2087,7 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
       status: settledStatus,
       ...settledStatus === "cancelled" ? { willRetry: false, failureStage: null } : settledStatus === "failed" && ctx._deliveryState ? failureRetryDecision(ctx._deliveryState, settledError) : { willRetry: null, failureStage: null },
       skipReason: settledStatus === "skipped" ? progress.skipReason : null,
+      retryAfter: settledStatus === "deferred" ? settledRetryAfter : null,
       sentCount: progress.sentCount,
       pushedCount: progress.pushedCount,
       total: progress.total,
@@ -2127,6 +2145,27 @@ async function runFireChain({
     progress.skipReason = "before-fire";
     return { handled: true, result: { success: true, messagesSent: 0, status: "skipped", iterations: 0 } };
   }
+  if (typeof before === "object" && !Array.isArray(before) && before.defer != null) {
+    const afterMs = readDeferAfterMs(before.defer);
+    if (ctx._deferSupported !== true) {
+      throw new DeploymentConfigError(
+        "AGENTIC_DEFER_UNSUPPORTED: onBeforeFire \u8FD4\u56DE\u4E86 { defer }\uFF0C\u4F46\u8FD9\u6761\u6295\u9012\u8DEF\u5F84\u4E0D\u652F\u6301\u63A8\u8FDF\u2014\u2014\u53EA\u6709 runScheduledTick / runTask \u4E14\u9002\u914D\u5668\u5B9E\u73B0\u4E86 claimTask\uFF08\u4EFB\u52A1\u8868\u6709 retry_after \u5217\uFF09\u65F6\u53EF\u7528\uFF0C\u8BF7\u6C42\u5185\u5F53\u573A\u6295\u9012\u7684 instant \u4EFB\u52A1\u4E0D\u53EF\u7528",
+        { code: "AGENTIC_DEFER_UNSUPPORTED" }
+      );
+    }
+    return {
+      handled: true,
+      result: {
+        success: false,
+        deferred: true,
+        // 用真实时钟：这个时刻要落进 retry_after，跟数据库捞取条件里的「现在」比。
+        retryAfter: new Date(Date.now() + afterMs).toISOString(),
+        messagesSent: 0,
+        status: "deferred",
+        iterations: 0
+      }
+    };
+  }
   const normalized = normalizeBeforeFireResult(before);
   const maxToolIterations = firstPositiveInt(
     [normalized.maxToolIterations, ctx.maxToolIterations],
@@ -3240,6 +3279,7 @@ async function deliverTasks(ctx, tasks) {
     deletedOnceOffTasks: 0,
     updatedRecurringTasks: 0,
     staleTasks: [],
+    deferredTasks: [],
     cancelledTasks: [],
     reasoningSkippedTasks: [],
     redeliveredTasks: [],
@@ -3533,7 +3573,7 @@ async function deliverTasks(ctx, tasks) {
     const occurrenceMs = Date.parse(task.next_send_at);
     const retryAfterMs = task.retry_after ? Date.parse(task.retry_after) : NaN;
     const notOnFreshRetryChain = (task.retry_count || 0) === 0 || Number.isFinite(retryAfterMs) && Date.now() - retryAfterMs > staleAfterMs;
-    if (Number.isFinite(occurrenceMs) && Date.now() - occurrenceMs > staleAfterMs && notOnFreshRetryChain) {
+    const settleAsStale = async () => {
       try {
         const stateAccessors = createStateAccessors({
           db,
@@ -3593,8 +3633,32 @@ async function deliverTasks(ctx, tasks) {
         results.failedCount++;
         results.failedTasks.push({ taskId: task.id, reason: error.message || "\u8FC7\u671F\u4EFB\u52A1\u5904\u7406\u5931\u8D25", status: "stale_update_failed" });
       }
+    };
+    if (Number.isFinite(occurrenceMs) && Date.now() - occurrenceMs > staleAfterMs && notOnFreshRetryChain) {
+      await settleAsStale();
       return;
     }
+    const handleDeferred = async (retryAfter) => {
+      const wakeMs = Date.parse(retryAfter);
+      if (Number.isFinite(occurrenceMs) && wakeMs - occurrenceMs > staleAfterMs) {
+        await settleAsStale();
+        return;
+      }
+      try {
+        const updated = await updateTaskWithLastError(task.id, {
+          retry_after: retryAfter,
+          lease_until: null
+        });
+        if (rowVanished(updated)) {
+          await recordCancelled(task, "cancelled_mid_delivery");
+          return;
+        }
+        results.deferredTasks.push({ taskId: task.id, retryAfter });
+      } catch (error) {
+        results.failedCount++;
+        results.failedTasks.push({ taskId: task.id, reason: error.message || "\u63A8\u8FDF\u5199\u5E93\u5931\u8D25", status: "defer_update_failed" });
+      }
+    };
     let sendResult;
     try {
       sendResult = await processSingleMessage(
@@ -3605,7 +3669,11 @@ async function deliverTasks(ctx, tasks) {
           masterKey,
           webpush: guardWebpushWithLease(ctx.webpush, lease),
           isTaskCancelled: () => lease.lost,
-          signal: lease.signal
+          signal: lease.signal,
+          // onBeforeFire 的 { defer } 要靠 retry_after 这一列落地，没实现
+          // claimTask 的适配器没有这一列（见 lib/agentic-fire.js 的
+          // AGENTIC_DEFER_UNSUPPORTED）。
+          _deferSupported: supportsClaim
         },
         masterKey,
         { userKey, payload: decryptedPayload }
@@ -3625,6 +3693,14 @@ async function deliverTasks(ctx, tasks) {
       );
       return;
     }
+    if (sendResult.deferred) {
+      if (lease.lost) {
+        await recordCancelled(task, "cancelled_mid_delivery");
+        return;
+      }
+      await handleDeferred(sendResult.retryAfter);
+      return;
+    }
     if (!sendResult.success) {
       if (lease.lost) {
         await recordCancelled(task, "cancelled_mid_delivery");
@@ -3717,6 +3793,9 @@ async function deliverTasks(ctx, tasks) {
       deletedOnceOffTasks: results.deletedOnceOffTasks,
       updatedRecurringTasks: results.updatedRecurringTasks,
       staleTasks: results.staleTasks,
+      // onBeforeFire 返回 { defer } 被推迟的任务（{ taskId, retryAfter }）：这一
+      // 跳没生成也没发，到 retryAfter 之后再问。不计入 successCount / failedCount。
+      deferredTasks: results.deferredTasks,
       // 投递期间行被取消 / 顶替的任务。`cancelled_mid_delivery` = 推送在发出去
       // 之前被拦下；`cancelled_after_delivery` = 推送已经发完，收尾写库才发现
       // 行没了。两种都不计入 successCount / failedCount。
@@ -6012,7 +6091,7 @@ function createClientStateNamespacesHandler(ctx) {
 }
 
 // src/server/lib/version.js
-var SERVER_VERSION = true ? "2.6.0-next.32" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.6.0-next.33" : "0.0.0-dev";
 
 // src/server/handlers/capabilities.js
 var SERVER_FEATURES = Object.freeze([
@@ -6125,7 +6204,10 @@ var SERVER_FEATURES = Object.freeze([
   // 工厂配置认 maxDeliveryRetries（投递失败的重试次数上限，默认 3）。
   "max-delivery-retries",
   // Per-task pre-commit retry limit and fire receipt retry decision.
-  "max-generation-retries"
+  "max-generation-retries",
+  // onBeforeFire 认 { defer: { afterMs } }：这次不生成，过一会儿再来问（不占重试
+  // 次数）；onFireSettled 的 status 多一种 'deferred'，带 retryAfter。
+  "before-fire-defer"
 ]);
 function createCapabilitiesHandler(ctx) {
   async function GET(url, headers) {
@@ -6753,4 +6835,5 @@ function createSingleUserCloudflareWorker(buildConfig, options = {}) {
 
 
 
-exports.isValidTimeZoneId = isValidTimeZoneId; exports.advanceOccurrence = advanceOccurrence; exports.planNextOccurrence = planNextOccurrence; exports.nextFutureOccurrence = nextFutureOccurrence; exports.base64UrlToBytes = _amsgshared.base64UrlToBytes; exports.utf8 = _amsgshared.utf8; exports.utf8Decode = _amsgshared.utf8Decode; exports.bytesToBase64Url = _amsgshared.bytesToBase64Url; exports.timingSafeEqualBytes = _amsgshared.timingSafeEqualBytes; exports.deriveUserEncryptionKey = deriveUserEncryptionKey; exports.decryptPayload = decryptPayload; exports.encryptForStorage = encryptForStorage; exports.decryptFromStorage = decryptFromStorage; exports.CRED_ID_MAX_LENGTH = CRED_ID_MAX_LENGTH; exports.CRED_PUT_BATCH_MAX = CRED_PUT_BATCH_MAX; exports.CRED_ROWS_PER_USER_MAX = CRED_ROWS_PER_USER_MAX; exports.CRED_REFS_MAX_ENTRIES = CRED_REFS_MAX_ENTRIES; exports.supportsLlmCredentialsStore = supportsLlmCredentialsStore; exports.isValidCredId = isValidCredId; exports.validateCredValue = validateCredValue; exports.validateCredRefs = validateCredRefs; exports.hasChatCredRef = hasChatCredRef; exports.resolveLlmCredential = resolveLlmCredential; exports.isValidUrl = _amsgshared.isValidUrl; exports.validateAvatarUrl = _amsgshared.validateAvatarUrl; exports.isValidISO8601 = isValidISO8601; exports.isValidUUID = isValidUUID; exports.isValidUUIDv4 = isValidUUIDv4; exports.validateSplitPattern = validateSplitPattern; exports.validateLlmMessagesArray = validateLlmMessagesArray; exports.MAX_TASK_PAYLOAD_BYTES = MAX_TASK_PAYLOAD_BYTES; exports.validateScheduleMessagePayload = validateScheduleMessagePayload; exports.DEFAULT_MAX_REQUEST_BODY_BYTES = DEFAULT_MAX_REQUEST_BODY_BYTES; exports.readRequestBody = readRequestBody; exports.parseJsonBody = parseJsonBody; exports.getHeader = getHeader; exports.createGetUserKeyHandler = createGetUserKeyHandler; exports.NonRetryableError = NonRetryableError; exports.isNonRetryableError = isNonRetryableError; exports.DeploymentConfigError = DeploymentConfigError; exports.sanitizeErrorSummary = sanitizeErrorSummary; exports.summarizeErrorCause = summarizeErrorCause; exports.DEFAULT_MAX_DELIVERY_RETRIES = DEFAULT_MAX_DELIVERY_RETRIES; exports.WEB_PUSH_MAX_BODY_BYTES = WEB_PUSH_MAX_BODY_BYTES; exports.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES; exports.MAX_PUSH_PAYLOAD_BYTES = MAX_PUSH_PAYLOAD_BYTES; exports.PUSH_ENVELOPE_RESERVED_BYTES = PUSH_ENVELOPE_RESERVED_BYTES; exports.measurePushPayload = measurePushPayload; exports.createWebCryptoWebPush = createWebCryptoWebPush; exports.DEFAULT_MAX_TOOL_ITERATIONS = DEFAULT_MAX_TOOL_ITERATIONS; exports.DEFAULT_TOTAL_TIMEOUT_MS = DEFAULT_TOTAL_TIMEOUT_MS; exports.DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE = DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE; exports.MIN_SCHEDULE_LEAD_MS = MIN_SCHEDULE_LEAD_MS; exports.createScheduleMessageHandler = createScheduleMessageHandler; exports.DEFAULT_CLAIM_LEASE_MS = DEFAULT_CLAIM_LEASE_MS; exports.DEFAULT_LEASE_HEARTBEAT_MS = DEFAULT_LEASE_HEARTBEAT_MS; exports.DEFAULT_HEARTBEAT_LEASE_TTL_MS = DEFAULT_HEARTBEAT_LEASE_TTL_MS; exports.runScheduledTick = runScheduledTick; exports.runTask = runTask; exports.createUpdateMessageHandler = createUpdateMessageHandler; exports.createCancelMessageHandler = createCancelMessageHandler; exports.createMessagesHandler = createMessagesHandler; exports.createGetMessageHandler = createGetMessageHandler; exports.createPushSubscriptionHandler = createPushSubscriptionHandler; exports.createLlmCredentialsHandler = createLlmCredentialsHandler; exports.createD1Adapter = createD1Adapter; exports.createSingleUserServer = createSingleUserServer; exports.SCHEMA_VERSION = SCHEMA_VERSION; exports.getSchemaVersion = getSchemaVersion; exports.ensureSchema = ensureSchema; exports.CORS_ALLOW_HEADERS = CORS_ALLOW_HEADERS; exports.CORS_ALLOW_METHODS = CORS_ALLOW_METHODS; exports.createSingleUserCloudflareWorker = createSingleUserCloudflareWorker;
+
+exports.isValidTimeZoneId = isValidTimeZoneId; exports.advanceOccurrence = advanceOccurrence; exports.planNextOccurrence = planNextOccurrence; exports.nextFutureOccurrence = nextFutureOccurrence; exports.base64UrlToBytes = _amsgshared.base64UrlToBytes; exports.utf8 = _amsgshared.utf8; exports.utf8Decode = _amsgshared.utf8Decode; exports.bytesToBase64Url = _amsgshared.bytesToBase64Url; exports.timingSafeEqualBytes = _amsgshared.timingSafeEqualBytes; exports.deriveUserEncryptionKey = deriveUserEncryptionKey; exports.decryptPayload = decryptPayload; exports.encryptForStorage = encryptForStorage; exports.decryptFromStorage = decryptFromStorage; exports.CRED_ID_MAX_LENGTH = CRED_ID_MAX_LENGTH; exports.CRED_PUT_BATCH_MAX = CRED_PUT_BATCH_MAX; exports.CRED_ROWS_PER_USER_MAX = CRED_ROWS_PER_USER_MAX; exports.CRED_REFS_MAX_ENTRIES = CRED_REFS_MAX_ENTRIES; exports.supportsLlmCredentialsStore = supportsLlmCredentialsStore; exports.isValidCredId = isValidCredId; exports.validateCredValue = validateCredValue; exports.validateCredRefs = validateCredRefs; exports.hasChatCredRef = hasChatCredRef; exports.resolveLlmCredential = resolveLlmCredential; exports.isValidUrl = _amsgshared.isValidUrl; exports.validateAvatarUrl = _amsgshared.validateAvatarUrl; exports.isValidISO8601 = isValidISO8601; exports.isValidUUID = isValidUUID; exports.isValidUUIDv4 = isValidUUIDv4; exports.validateSplitPattern = validateSplitPattern; exports.validateLlmMessagesArray = validateLlmMessagesArray; exports.MAX_TASK_PAYLOAD_BYTES = MAX_TASK_PAYLOAD_BYTES; exports.validateScheduleMessagePayload = validateScheduleMessagePayload; exports.DEFAULT_MAX_REQUEST_BODY_BYTES = DEFAULT_MAX_REQUEST_BODY_BYTES; exports.readRequestBody = readRequestBody; exports.parseJsonBody = parseJsonBody; exports.getHeader = getHeader; exports.createGetUserKeyHandler = createGetUserKeyHandler; exports.NonRetryableError = NonRetryableError; exports.isNonRetryableError = isNonRetryableError; exports.DeploymentConfigError = DeploymentConfigError; exports.sanitizeErrorSummary = sanitizeErrorSummary; exports.summarizeErrorCause = summarizeErrorCause; exports.DEFAULT_MAX_DELIVERY_RETRIES = DEFAULT_MAX_DELIVERY_RETRIES; exports.WEB_PUSH_MAX_BODY_BYTES = WEB_PUSH_MAX_BODY_BYTES; exports.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES; exports.MAX_PUSH_PAYLOAD_BYTES = MAX_PUSH_PAYLOAD_BYTES; exports.PUSH_ENVELOPE_RESERVED_BYTES = PUSH_ENVELOPE_RESERVED_BYTES; exports.measurePushPayload = measurePushPayload; exports.createWebCryptoWebPush = createWebCryptoWebPush; exports.DEFAULT_MAX_TOOL_ITERATIONS = DEFAULT_MAX_TOOL_ITERATIONS; exports.DEFAULT_TOTAL_TIMEOUT_MS = DEFAULT_TOTAL_TIMEOUT_MS; exports.DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE = DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE; exports.MIN_SCHEDULE_LEAD_MS = MIN_SCHEDULE_LEAD_MS; exports.MAX_DEFER_AFTER_MS = MAX_DEFER_AFTER_MS; exports.createScheduleMessageHandler = createScheduleMessageHandler; exports.DEFAULT_CLAIM_LEASE_MS = DEFAULT_CLAIM_LEASE_MS; exports.DEFAULT_LEASE_HEARTBEAT_MS = DEFAULT_LEASE_HEARTBEAT_MS; exports.DEFAULT_HEARTBEAT_LEASE_TTL_MS = DEFAULT_HEARTBEAT_LEASE_TTL_MS; exports.runScheduledTick = runScheduledTick; exports.runTask = runTask; exports.createUpdateMessageHandler = createUpdateMessageHandler; exports.createCancelMessageHandler = createCancelMessageHandler; exports.createMessagesHandler = createMessagesHandler; exports.createGetMessageHandler = createGetMessageHandler; exports.createPushSubscriptionHandler = createPushSubscriptionHandler; exports.createLlmCredentialsHandler = createLlmCredentialsHandler; exports.createD1Adapter = createD1Adapter; exports.createSingleUserServer = createSingleUserServer; exports.SCHEMA_VERSION = SCHEMA_VERSION; exports.getSchemaVersion = getSchemaVersion; exports.ensureSchema = ensureSchema; exports.CORS_ALLOW_HEADERS = CORS_ALLOW_HEADERS; exports.CORS_ALLOW_METHODS = CORS_ALLOW_METHODS; exports.createSingleUserCloudflareWorker = createSingleUserCloudflareWorker;

package/dist/{chunk-INNZZFGJ.mjs → chunk-Q4VQ3NVR.mjs}

@@ -1636,6 +1636,7 @@ 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 MAX_DEFER_AFTER_MS = 24 * 60 * 60 * 1e3;
 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;
@@ -1670,6 +1671,22 @@ function buildHookTask(task, decryptedPayload) {
     retryCount: task.retry_count ?? 0
   });
 }
+var BAD_BEFORE_FIRE_MESSAGE = "AGENTIC_BAD_BEFORE_FIRE: onBeforeFire must return ChatMessage[] | { messages, maxToolIterations?, totalTimeoutMs?, tools?, toolChoice? } | { skip: true } | { defer: { afterMs } } | null";
+function readDeferAfterMs(defer) {
+  const afterMs = defer && typeof defer === "object" ? (
+    /** @type {any} */
+    defer.afterMs
+  ) : void 0;
+  if (typeof afterMs !== "number" || !Number.isFinite(afterMs) || afterMs <= 0 || afterMs > MAX_DEFER_AFTER_MS) {
+    throw markPermanent(
+      new TypeError(
+        `${BAD_BEFORE_FIRE_MESSAGE}\uFF08defer.afterMs \u5FC5\u987B\u662F\u6709\u9650\u6B63\u6570\uFF0C\u4E14\u4E0D\u8D85\u8FC7 ${MAX_DEFER_AFTER_MS} \u6BEB\u79D2\uFF09`
+      ),
+      "AGENTIC_BAD_BEFORE_FIRE"
+    );
+  }
+  return afterMs;
+}
 function normalizeBeforeFireResult(result) {
   if (Array.isArray(result)) {
     return { messages: result };
@@ -1686,12 +1703,7 @@ function normalizeBeforeFireResult(result) {
       toolChoice: result.toolChoice
     };
   }
-  throw markPermanent(
-    new TypeError(
-      "AGENTIC_BAD_BEFORE_FIRE: onBeforeFire must return ChatMessage[] | { messages, maxToolIterations?, totalTimeoutMs?, tools?, toolChoice? } | { skip: true } | null"
-    ),
-    "AGENTIC_BAD_BEFORE_FIRE"
-  );
+  throw markPermanent(new TypeError(BAD_BEFORE_FIRE_MESSAGE), "AGENTIC_BAD_BEFORE_FIRE");
 }
 function firstPositiveInt(values, fallback) {
   for (const v of values) {
@@ -2026,6 +2038,7 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
   };
   let settledStatus = "failed";
   let settledError = null;
+  let settledRetryAfter = null;
   try {
     const outcome = await runFireChain({
       task,
@@ -2050,7 +2063,11 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
       occurrenceMs
     });
     throwIfCancelled();
-    settledStatus = !outcome.handled ? "not-handled" : outcome.result.status === "skipped" ? "skipped" : "sent";
+    if (!outcome.handled) settledStatus = "not-handled";
+    else if (outcome.result.status === "deferred") {
+      settledStatus = "deferred";
+      settledRetryAfter = outcome.result.retryAfter;
+    } else settledStatus = outcome.result.status === "skipped" ? "skipped" : "sent";
     return outcome;
   } catch (error) {
     if (isCancelled() && !isTaskCancelledError(error)) {
@@ -2070,6 +2087,7 @@ async function runAgenticFire({ task, decryptedPayload, userKey, ctx }) {
       status: settledStatus,
       ...settledStatus === "cancelled" ? { willRetry: false, failureStage: null } : settledStatus === "failed" && ctx._deliveryState ? failureRetryDecision(ctx._deliveryState, settledError) : { willRetry: null, failureStage: null },
       skipReason: settledStatus === "skipped" ? progress.skipReason : null,
+      retryAfter: settledStatus === "deferred" ? settledRetryAfter : null,
       sentCount: progress.sentCount,
       pushedCount: progress.pushedCount,
       total: progress.total,
@@ -2127,6 +2145,27 @@ async function runFireChain({
     progress.skipReason = "before-fire";
     return { handled: true, result: { success: true, messagesSent: 0, status: "skipped", iterations: 0 } };
   }
+  if (typeof before === "object" && !Array.isArray(before) && before.defer != null) {
+    const afterMs = readDeferAfterMs(before.defer);
+    if (ctx._deferSupported !== true) {
+      throw new DeploymentConfigError(
+        "AGENTIC_DEFER_UNSUPPORTED: onBeforeFire \u8FD4\u56DE\u4E86 { defer }\uFF0C\u4F46\u8FD9\u6761\u6295\u9012\u8DEF\u5F84\u4E0D\u652F\u6301\u63A8\u8FDF\u2014\u2014\u53EA\u6709 runScheduledTick / runTask \u4E14\u9002\u914D\u5668\u5B9E\u73B0\u4E86 claimTask\uFF08\u4EFB\u52A1\u8868\u6709 retry_after \u5217\uFF09\u65F6\u53EF\u7528\uFF0C\u8BF7\u6C42\u5185\u5F53\u573A\u6295\u9012\u7684 instant \u4EFB\u52A1\u4E0D\u53EF\u7528",
+        { code: "AGENTIC_DEFER_UNSUPPORTED" }
+      );
+    }
+    return {
+      handled: true,
+      result: {
+        success: false,
+        deferred: true,
+        // 用真实时钟：这个时刻要落进 retry_after，跟数据库捞取条件里的「现在」比。
+        retryAfter: new Date(Date.now() + afterMs).toISOString(),
+        messagesSent: 0,
+        status: "deferred",
+        iterations: 0
+      }
+    };
+  }
   const normalized = normalizeBeforeFireResult(before);
   const maxToolIterations = firstPositiveInt(
     [normalized.maxToolIterations, ctx.maxToolIterations],
@@ -3240,6 +3279,7 @@ async function deliverTasks(ctx, tasks) {
     deletedOnceOffTasks: 0,
     updatedRecurringTasks: 0,
     staleTasks: [],
+    deferredTasks: [],
     cancelledTasks: [],
     reasoningSkippedTasks: [],
     redeliveredTasks: [],
@@ -3533,7 +3573,7 @@ async function deliverTasks(ctx, tasks) {
     const occurrenceMs = Date.parse(task.next_send_at);
     const retryAfterMs = task.retry_after ? Date.parse(task.retry_after) : NaN;
     const notOnFreshRetryChain = (task.retry_count || 0) === 0 || Number.isFinite(retryAfterMs) && Date.now() - retryAfterMs > staleAfterMs;
-    if (Number.isFinite(occurrenceMs) && Date.now() - occurrenceMs > staleAfterMs && notOnFreshRetryChain) {
+    const settleAsStale = async () => {
       try {
         const stateAccessors = createStateAccessors({
           db,
@@ -3593,8 +3633,32 @@ async function deliverTasks(ctx, tasks) {
         results.failedCount++;
         results.failedTasks.push({ taskId: task.id, reason: error.message || "\u8FC7\u671F\u4EFB\u52A1\u5904\u7406\u5931\u8D25", status: "stale_update_failed" });
       }
+    };
+    if (Number.isFinite(occurrenceMs) && Date.now() - occurrenceMs > staleAfterMs && notOnFreshRetryChain) {
+      await settleAsStale();
       return;
     }
+    const handleDeferred = async (retryAfter) => {
+      const wakeMs = Date.parse(retryAfter);
+      if (Number.isFinite(occurrenceMs) && wakeMs - occurrenceMs > staleAfterMs) {
+        await settleAsStale();
+        return;
+      }
+      try {
+        const updated = await updateTaskWithLastError(task.id, {
+          retry_after: retryAfter,
+          lease_until: null
+        });
+        if (rowVanished(updated)) {
+          await recordCancelled(task, "cancelled_mid_delivery");
+          return;
+        }
+        results.deferredTasks.push({ taskId: task.id, retryAfter });
+      } catch (error) {
+        results.failedCount++;
+        results.failedTasks.push({ taskId: task.id, reason: error.message || "\u63A8\u8FDF\u5199\u5E93\u5931\u8D25", status: "defer_update_failed" });
+      }
+    };
     let sendResult;
     try {
       sendResult = await processSingleMessage(
@@ -3605,7 +3669,11 @@ async function deliverTasks(ctx, tasks) {
           masterKey,
           webpush: guardWebpushWithLease(ctx.webpush, lease),
           isTaskCancelled: () => lease.lost,
-          signal: lease.signal
+          signal: lease.signal,
+          // onBeforeFire 的 { defer } 要靠 retry_after 这一列落地，没实现
+          // claimTask 的适配器没有这一列（见 lib/agentic-fire.js 的
+          // AGENTIC_DEFER_UNSUPPORTED）。
+          _deferSupported: supportsClaim
         },
         masterKey,
         { userKey, payload: decryptedPayload }
@@ -3625,6 +3693,14 @@ async function deliverTasks(ctx, tasks) {
       );
       return;
     }
+    if (sendResult.deferred) {
+      if (lease.lost) {
+        await recordCancelled(task, "cancelled_mid_delivery");
+        return;
+      }
+      await handleDeferred(sendResult.retryAfter);
+      return;
+    }
     if (!sendResult.success) {
       if (lease.lost) {
         await recordCancelled(task, "cancelled_mid_delivery");
@@ -3717,6 +3793,9 @@ async function deliverTasks(ctx, tasks) {
       deletedOnceOffTasks: results.deletedOnceOffTasks,
       updatedRecurringTasks: results.updatedRecurringTasks,
       staleTasks: results.staleTasks,
+      // onBeforeFire 返回 { defer } 被推迟的任务（{ taskId, retryAfter }）：这一
+      // 跳没生成也没发，到 retryAfter 之后再问。不计入 successCount / failedCount。
+      deferredTasks: results.deferredTasks,
       // 投递期间行被取消 / 顶替的任务。`cancelled_mid_delivery` = 推送在发出去
       // 之前被拦下；`cancelled_after_delivery` = 推送已经发完，收尾写库才发现
       // 行没了。两种都不计入 successCount / failedCount。
@@ -6012,7 +6091,7 @@ function createClientStateNamespacesHandler(ctx) {
 }
 
 // src/server/lib/version.js
-var SERVER_VERSION = true ? "2.6.0-next.32" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.6.0-next.33" : "0.0.0-dev";
 
 // src/server/handlers/capabilities.js
 var SERVER_FEATURES = Object.freeze([
@@ -6125,7 +6204,10 @@ var SERVER_FEATURES = Object.freeze([
   // 工厂配置认 maxDeliveryRetries（投递失败的重试次数上限，默认 3）。
   "max-delivery-retries",
   // Per-task pre-commit retry limit and fire receipt retry decision.
-  "max-generation-retries"
+  "max-generation-retries",
+  // onBeforeFire 认 { defer: { afterMs } }：这次不生成，过一会儿再来问（不占重试
+  // 次数）；onFireSettled 的 status 多一种 'deferred'，带 retryAfter。
+  "before-fire-defer"
 ]);
 function createCapabilitiesHandler(ctx) {
   async function GET(url, headers) {
@@ -6733,6 +6815,7 @@ export {
   DEFAULT_TOTAL_TIMEOUT_MS,
   DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE,
   MIN_SCHEDULE_LEAD_MS,
+  MAX_DEFER_AFTER_MS,
   createScheduleMessageHandler,
   DEFAULT_CLAIM_LEASE_MS,
   DEFAULT_LEASE_HEARTBEAT_MS,

package/dist/cloudflare.cjs

@@ -27,7 +27,8 @@
 
 
 
-var _chunkKZT3YC62cjs = require('./chunk-KZT3YC62.cjs');
+
+var _chunkAM2MMY46cjs = require('./chunk-AM2MMY46.cjs');
 require('./chunk-7NMQFTDJ.cjs');
 
 
@@ -58,4 +59,5 @@ require('./chunk-7NMQFTDJ.cjs');
 
 
 
-exports.DEFAULT_MAX_DELIVERY_RETRIES = _chunkKZT3YC62cjs.DEFAULT_MAX_DELIVERY_RETRIES; exports.DEFAULT_MAX_REQUEST_BODY_BYTES = _chunkKZT3YC62cjs.DEFAULT_MAX_REQUEST_BODY_BYTES; exports.MAX_PUSH_PAYLOAD_BYTES = _chunkKZT3YC62cjs.MAX_PUSH_PAYLOAD_BYTES; exports.NonRetryableError = _chunkKZT3YC62cjs.NonRetryableError; exports.PUSH_ENVELOPE_RESERVED_BYTES = _chunkKZT3YC62cjs.PUSH_ENVELOPE_RESERVED_BYTES; exports.SCHEMA_VERSION = _chunkKZT3YC62cjs.SCHEMA_VERSION; exports.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = _chunkKZT3YC62cjs.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES; exports.WEB_PUSH_MAX_BODY_BYTES = _chunkKZT3YC62cjs.WEB_PUSH_MAX_BODY_BYTES; exports.advanceOccurrence = _chunkKZT3YC62cjs.advanceOccurrence; exports.createD1Adapter = _chunkKZT3YC62cjs.createD1Adapter; exports.createSingleUserCloudflareWorker = _chunkKZT3YC62cjs.createSingleUserCloudflareWorker; exports.createSingleUserServer = _chunkKZT3YC62cjs.createSingleUserServer; exports.createWebCryptoWebPush = _chunkKZT3YC62cjs.createWebCryptoWebPush; exports.decryptFromStorage = _chunkKZT3YC62cjs.decryptFromStorage; exports.decryptPayload = _chunkKZT3YC62cjs.decryptPayload; exports.deriveUserEncryptionKey = _chunkKZT3YC62cjs.deriveUserEncryptionKey; exports.encryptForStorage = _chunkKZT3YC62cjs.encryptForStorage; exports.ensureSchema = _chunkKZT3YC62cjs.ensureSchema; exports.getSchemaVersion = _chunkKZT3YC62cjs.getSchemaVersion; exports.isNonRetryableError = _chunkKZT3YC62cjs.isNonRetryableError; exports.isValidTimeZoneId = _chunkKZT3YC62cjs.isValidTimeZoneId; exports.measurePushPayload = _chunkKZT3YC62cjs.measurePushPayload; exports.nextFutureOccurrence = _chunkKZT3YC62cjs.nextFutureOccurrence; exports.planNextOccurrence = _chunkKZT3YC62cjs.planNextOccurrence; exports.readRequestBody = _chunkKZT3YC62cjs.readRequestBody; exports.runScheduledTick = _chunkKZT3YC62cjs.runScheduledTick; exports.runTask = _chunkKZT3YC62cjs.runTask; exports.summarizeErrorCause = _chunkKZT3YC62cjs.summarizeErrorCause;
+
+exports.DEFAULT_MAX_DELIVERY_RETRIES = _chunkAM2MMY46cjs.DEFAULT_MAX_DELIVERY_RETRIES; exports.DEFAULT_MAX_REQUEST_BODY_BYTES = _chunkAM2MMY46cjs.DEFAULT_MAX_REQUEST_BODY_BYTES; exports.MAX_DEFER_AFTER_MS = _chunkAM2MMY46cjs.MAX_DEFER_AFTER_MS; exports.MAX_PUSH_PAYLOAD_BYTES = _chunkAM2MMY46cjs.MAX_PUSH_PAYLOAD_BYTES; exports.NonRetryableError = _chunkAM2MMY46cjs.NonRetryableError; exports.PUSH_ENVELOPE_RESERVED_BYTES = _chunkAM2MMY46cjs.PUSH_ENVELOPE_RESERVED_BYTES; exports.SCHEMA_VERSION = _chunkAM2MMY46cjs.SCHEMA_VERSION; exports.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = _chunkAM2MMY46cjs.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES; exports.WEB_PUSH_MAX_BODY_BYTES = _chunkAM2MMY46cjs.WEB_PUSH_MAX_BODY_BYTES; exports.advanceOccurrence = _chunkAM2MMY46cjs.advanceOccurrence; exports.createD1Adapter = _chunkAM2MMY46cjs.createD1Adapter; exports.createSingleUserCloudflareWorker = _chunkAM2MMY46cjs.createSingleUserCloudflareWorker; exports.createSingleUserServer = _chunkAM2MMY46cjs.createSingleUserServer; exports.createWebCryptoWebPush = _chunkAM2MMY46cjs.createWebCryptoWebPush; exports.decryptFromStorage = _chunkAM2MMY46cjs.decryptFromStorage; exports.decryptPayload = _chunkAM2MMY46cjs.decryptPayload; exports.deriveUserEncryptionKey = _chunkAM2MMY46cjs.deriveUserEncryptionKey; exports.encryptForStorage = _chunkAM2MMY46cjs.encryptForStorage; exports.ensureSchema = _chunkAM2MMY46cjs.ensureSchema; exports.getSchemaVersion = _chunkAM2MMY46cjs.getSchemaVersion; exports.isNonRetryableError = _chunkAM2MMY46cjs.isNonRetryableError; exports.isValidTimeZoneId = _chunkAM2MMY46cjs.isValidTimeZoneId; exports.measurePushPayload = _chunkAM2MMY46cjs.measurePushPayload; exports.nextFutureOccurrence = _chunkAM2MMY46cjs.nextFutureOccurrence; exports.planNextOccurrence = _chunkAM2MMY46cjs.planNextOccurrence; exports.readRequestBody = _chunkAM2MMY46cjs.readRequestBody; exports.runScheduledTick = _chunkAM2MMY46cjs.runScheduledTick; exports.runTask = _chunkAM2MMY46cjs.runTask; exports.summarizeErrorCause = _chunkAM2MMY46cjs.summarizeErrorCause;

package/dist/cloudflare.d.ts

@@ -1,6 +1,7 @@
 export { createSingleUserCloudflareWorker } from "./cloudflare/single-user-worker.js";
 export { createSingleUserServer } from "./single-user.js";
 export { createD1Adapter } from "./adapters/d1.js";
+export { MAX_DEFER_AFTER_MS } from "./lib/agentic-fire.js";
 export { createWebCryptoWebPush, measurePushPayload, MAX_PUSH_PAYLOAD_BYTES, PUSH_ENVELOPE_RESERVED_BYTES, WEB_PUSH_MAX_BODY_BYTES, WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES } from "./lib/webpush-webcrypto.js";
 export { runScheduledTick, runTask, DEFAULT_MAX_DELIVERY_RETRIES } from "./lib/run-tick.js";
 export { getSchemaVersion, ensureSchema, SCHEMA_VERSION } from "./lib/schema-version.js";

package/dist/cloudflare.mjs

@@ -1,6 +1,7 @@
 import {
   DEFAULT_MAX_DELIVERY_RETRIES,
   DEFAULT_MAX_REQUEST_BODY_BYTES,
+  MAX_DEFER_AFTER_MS,
   MAX_PUSH_PAYLOAD_BYTES,
   NonRetryableError,
   PUSH_ENVELOPE_RESERVED_BYTES,
@@ -27,11 +28,12 @@ import {
   runScheduledTick,
   runTask,
   summarizeErrorCause
-} from "./chunk-INNZZFGJ.mjs";
+} from "./chunk-Q4VQ3NVR.mjs";
 import "./chunk-GN44PST5.mjs";
 export {
   DEFAULT_MAX_DELIVERY_RETRIES,
   DEFAULT_MAX_REQUEST_BODY_BYTES,
+  MAX_DEFER_AFTER_MS,
   MAX_PUSH_PAYLOAD_BYTES,
   NonRetryableError,
   PUSH_ENVELOPE_RESERVED_BYTES,

package/dist/index.cjs

@@ -72,7 +72,8 @@
 
 
 
-var _chunkKZT3YC62cjs = require('./chunk-KZT3YC62.cjs');
+
+var _chunkAM2MMY46cjs = require('./chunk-AM2MMY46.cjs');
 require('./chunk-7NMQFTDJ.cjs');
 
 // src/server/adapters/factory.js
@@ -106,7 +107,7 @@ async function createAdapter(config) {
 // src/server/handlers/init-tenant.js
 function createInitTenantHandler(ctx) {
   async function POST(headers, body) {
-    const initSecret = _chunkKZT3YC62cjs.getHeader.call(void 0, headers, "x-init-secret");
+    const initSecret = _chunkAM2MMY46cjs.getHeader.call(void 0, headers, "x-init-secret");
     if (ctx.tenant.initSecret && initSecret !== ctx.tenant.initSecret) {
       return {
         status: 401,
@@ -119,7 +120,7 @@ function createInitTenantHandler(ctx) {
         }
       };
     }
-    const parsed = _chunkKZT3YC62cjs.parseJsonBody.call(void 0, body);
+    const parsed = _chunkAM2MMY46cjs.parseJsonBody.call(void 0, body);
     if (!parsed.ok) {
       return {
         status: 400,
@@ -133,7 +134,7 @@ function createInitTenantHandler(ctx) {
     const tenantId = payload.tenantId || void 0;
     const driver = payload.driver;
     const databaseUrl = payload.databaseUrl || payload.connectionString;
-    if (tenantId && !_chunkKZT3YC62cjs.isValidUUIDv4.call(void 0, tenantId)) {
+    if (tenantId && !_chunkAM2MMY46cjs.isValidUUIDv4.call(void 0, tenantId)) {
       return {
         status: 400,
         body: {
@@ -253,7 +254,7 @@ function createSendNotificationsHandler(ctx) {
         }
       };
     }
-    const data = await _chunkKZT3YC62cjs.runScheduledTick.call(void 0, { ...ctx, db, masterKey });
+    const data = await _chunkAM2MMY46cjs.runScheduledTick.call(void 0, { ...ctx, db, masterKey });
     return { status: 200, body: { success: true, data } };
   }
   return { POST };
@@ -275,16 +276,16 @@ function encryptConfig(config, kekBuffer) {
   const plaintext = Buffer.from(JSON.stringify(config), "utf8");
   const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
   const authTag = cipher.getAuthTag();
-  return `v1.${_chunkKZT3YC62cjs.bytesToBase64Url.call(void 0, iv)}.${_chunkKZT3YC62cjs.bytesToBase64Url.call(void 0, authTag)}.${_chunkKZT3YC62cjs.bytesToBase64Url.call(void 0, ciphertext)}`;
+  return `v1.${_chunkAM2MMY46cjs.bytesToBase64Url.call(void 0, iv)}.${_chunkAM2MMY46cjs.bytesToBase64Url.call(void 0, authTag)}.${_chunkAM2MMY46cjs.bytesToBase64Url.call(void 0, ciphertext)}`;
 }
 function decryptConfig(encrypted, kekBuffer) {
   const parts = String(encrypted || "").split(".");
   if (parts.length !== 4 || parts[0] !== "v1") {
     throw new Error("INVALID_TENANT_CONFIG");
   }
-  const iv = _chunkKZT3YC62cjs.base64UrlToBytes.call(void 0, parts[1]);
-  const authTag = _chunkKZT3YC62cjs.base64UrlToBytes.call(void 0, parts[2]);
-  const ciphertext = _chunkKZT3YC62cjs.base64UrlToBytes.call(void 0, parts[3]);
+  const iv = _chunkAM2MMY46cjs.base64UrlToBytes.call(void 0, parts[1]);
+  const authTag = _chunkAM2MMY46cjs.base64UrlToBytes.call(void 0, parts[2]);
+  const ciphertext = _chunkAM2MMY46cjs.base64UrlToBytes.call(void 0, parts[3]);
   const decipher = _crypto.createDecipheriv.call(void 0, "aes-256-gcm", kekBuffer, iv);
   decipher.setAuthTag(authTag);
   const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
@@ -352,7 +353,7 @@ function createTenantBlobStore(options) {
 // src/server/tenant/token.js
 
 function sign(input, secret) {
-  return _chunkKZT3YC62cjs.bytesToBase64Url.call(void 0, _crypto.createHmac.call(void 0, "sha256", secret).update(input).digest());
+  return _chunkAM2MMY46cjs.bytesToBase64Url.call(void 0, _crypto.createHmac.call(void 0, "sha256", secret).update(input).digest());
 }
 function nowEpochSeconds() {
   return Math.floor(Date.now() / 1e3);
@@ -368,8 +369,8 @@ function createTenantToken(params, secret) {
     v: 1
   };
   const header = { alg: "HS256", typ: "JWT" };
-  const encodedHeader = _chunkKZT3YC62cjs.bytesToBase64Url.call(void 0, _chunkKZT3YC62cjs.utf8.call(void 0, JSON.stringify(header)));
-  const encodedPayload = _chunkKZT3YC62cjs.bytesToBase64Url.call(void 0, _chunkKZT3YC62cjs.utf8.call(void 0, JSON.stringify(payload)));
+  const encodedHeader = _chunkAM2MMY46cjs.bytesToBase64Url.call(void 0, _chunkAM2MMY46cjs.utf8.call(void 0, JSON.stringify(header)));
+  const encodedPayload = _chunkAM2MMY46cjs.bytesToBase64Url.call(void 0, _chunkAM2MMY46cjs.utf8.call(void 0, JSON.stringify(payload)));
   const signingInput = `${encodedHeader}.${encodedPayload}`;
   const signature = sign(signingInput, secret);
   return `${signingInput}.${signature}`;
@@ -388,17 +389,17 @@ function verifyTenantToken(token, secret, options = {}) {
   let receivedBytes;
   let expectedBytes;
   try {
-    receivedBytes = _chunkKZT3YC62cjs.base64UrlToBytes.call(void 0, receivedSignature);
-    expectedBytes = _chunkKZT3YC62cjs.base64UrlToBytes.call(void 0, expectedSignature);
+    receivedBytes = _chunkAM2MMY46cjs.base64UrlToBytes.call(void 0, receivedSignature);
+    expectedBytes = _chunkAM2MMY46cjs.base64UrlToBytes.call(void 0, expectedSignature);
   } catch (e) {
     throw new Error("INVALID_TENANT_AUTH");
   }
-  if (!_chunkKZT3YC62cjs.timingSafeEqualBytes.call(void 0, receivedBytes, expectedBytes)) {
+  if (!_chunkAM2MMY46cjs.timingSafeEqualBytes.call(void 0, receivedBytes, expectedBytes)) {
     throw new Error("INVALID_TENANT_AUTH");
   }
   let payload;
   try {
-    payload = JSON.parse(_chunkKZT3YC62cjs.utf8Decode.call(void 0, _chunkKZT3YC62cjs.base64UrlToBytes.call(void 0, encodedPayload)));
+    payload = JSON.parse(_chunkAM2MMY46cjs.utf8Decode.call(void 0, _chunkAM2MMY46cjs.base64UrlToBytes.call(void 0, encodedPayload)));
   } catch (e2) {
     throw new Error("INVALID_TENANT_AUTH");
   }
@@ -626,15 +627,15 @@ async function createReiServer(config) {
   return {
     handlers: {
       initTenant: createInitTenantHandler(ctx),
-      getUserKey: _chunkKZT3YC62cjs.createGetUserKeyHandler.call(void 0, ctx),
-      scheduleMessage: _chunkKZT3YC62cjs.createScheduleMessageHandler.call(void 0, ctx),
+      getUserKey: _chunkAM2MMY46cjs.createGetUserKeyHandler.call(void 0, ctx),
+      scheduleMessage: _chunkAM2MMY46cjs.createScheduleMessageHandler.call(void 0, ctx),
       sendNotifications: createSendNotificationsHandler(ctx),
-      updateMessage: _chunkKZT3YC62cjs.createUpdateMessageHandler.call(void 0, ctx),
-      cancelMessage: _chunkKZT3YC62cjs.createCancelMessageHandler.call(void 0, ctx),
-      messages: _chunkKZT3YC62cjs.createMessagesHandler.call(void 0, ctx),
-      getMessage: _chunkKZT3YC62cjs.createGetMessageHandler.call(void 0, ctx),
-      pushSubscription: _chunkKZT3YC62cjs.createPushSubscriptionHandler.call(void 0, ctx),
-      llmCredentials: _chunkKZT3YC62cjs.createLlmCredentialsHandler.call(void 0, ctx)
+      updateMessage: _chunkAM2MMY46cjs.createUpdateMessageHandler.call(void 0, ctx),
+      cancelMessage: _chunkAM2MMY46cjs.createCancelMessageHandler.call(void 0, ctx),
+      messages: _chunkAM2MMY46cjs.createMessagesHandler.call(void 0, ctx),
+      getMessage: _chunkAM2MMY46cjs.createGetMessageHandler.call(void 0, ctx),
+      pushSubscription: _chunkAM2MMY46cjs.createPushSubscriptionHandler.call(void 0, ctx),
+      llmCredentials: _chunkAM2MMY46cjs.createLlmCredentialsHandler.call(void 0, ctx)
     }
   };
 }
@@ -701,4 +702,5 @@ async function createReiServer(config) {
 
 
 
-exports.CORS_ALLOW_HEADERS = _chunkKZT3YC62cjs.CORS_ALLOW_HEADERS; exports.CORS_ALLOW_METHODS = _chunkKZT3YC62cjs.CORS_ALLOW_METHODS; exports.CRED_ID_MAX_LENGTH = _chunkKZT3YC62cjs.CRED_ID_MAX_LENGTH; exports.CRED_PUT_BATCH_MAX = _chunkKZT3YC62cjs.CRED_PUT_BATCH_MAX; exports.CRED_REFS_MAX_ENTRIES = _chunkKZT3YC62cjs.CRED_REFS_MAX_ENTRIES; exports.CRED_ROWS_PER_USER_MAX = _chunkKZT3YC62cjs.CRED_ROWS_PER_USER_MAX; exports.DEFAULT_CLAIM_LEASE_MS = _chunkKZT3YC62cjs.DEFAULT_CLAIM_LEASE_MS; exports.DEFAULT_HEARTBEAT_LEASE_TTL_MS = _chunkKZT3YC62cjs.DEFAULT_HEARTBEAT_LEASE_TTL_MS; exports.DEFAULT_LEASE_HEARTBEAT_MS = _chunkKZT3YC62cjs.DEFAULT_LEASE_HEARTBEAT_MS; exports.DEFAULT_MAX_DELIVERY_RETRIES = _chunkKZT3YC62cjs.DEFAULT_MAX_DELIVERY_RETRIES; exports.DEFAULT_MAX_REQUEST_BODY_BYTES = _chunkKZT3YC62cjs.DEFAULT_MAX_REQUEST_BODY_BYTES; exports.DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE = _chunkKZT3YC62cjs.DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE; exports.DEFAULT_MAX_TOOL_ITERATIONS = _chunkKZT3YC62cjs.DEFAULT_MAX_TOOL_ITERATIONS; exports.DEFAULT_TOTAL_TIMEOUT_MS = _chunkKZT3YC62cjs.DEFAULT_TOTAL_TIMEOUT_MS; exports.DeploymentConfigError = _chunkKZT3YC62cjs.DeploymentConfigError; exports.MAX_PUSH_PAYLOAD_BYTES = _chunkKZT3YC62cjs.MAX_PUSH_PAYLOAD_BYTES; exports.MAX_TASK_PAYLOAD_BYTES = _chunkKZT3YC62cjs.MAX_TASK_PAYLOAD_BYTES; exports.MIN_SCHEDULE_LEAD_MS = _chunkKZT3YC62cjs.MIN_SCHEDULE_LEAD_MS; exports.NonRetryableError = _chunkKZT3YC62cjs.NonRetryableError; exports.PUSH_ENVELOPE_RESERVED_BYTES = _chunkKZT3YC62cjs.PUSH_ENVELOPE_RESERVED_BYTES; exports.SCHEMA_VERSION = _chunkKZT3YC62cjs.SCHEMA_VERSION; exports.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = _chunkKZT3YC62cjs.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES; exports.WEB_PUSH_MAX_BODY_BYTES = _chunkKZT3YC62cjs.WEB_PUSH_MAX_BODY_BYTES; exports.advanceOccurrence = _chunkKZT3YC62cjs.advanceOccurrence; exports.createAdapter = createAdapter; exports.createD1Adapter = _chunkKZT3YC62cjs.createD1Adapter; exports.createReiServer = createReiServer; exports.createSingleUserCloudflareWorker = _chunkKZT3YC62cjs.createSingleUserCloudflareWorker; exports.createSingleUserServer = _chunkKZT3YC62cjs.createSingleUserServer; exports.createTenantToken = createTenantToken; exports.createWebCryptoWebPush = _chunkKZT3YC62cjs.createWebCryptoWebPush; exports.decryptFromStorage = _chunkKZT3YC62cjs.decryptFromStorage; exports.decryptPayload = _chunkKZT3YC62cjs.decryptPayload; exports.deriveUserEncryptionKey = _chunkKZT3YC62cjs.deriveUserEncryptionKey; exports.encryptForStorage = _chunkKZT3YC62cjs.encryptForStorage; exports.ensureSchema = _chunkKZT3YC62cjs.ensureSchema; exports.getSchemaVersion = _chunkKZT3YC62cjs.getSchemaVersion; exports.hasChatCredRef = _chunkKZT3YC62cjs.hasChatCredRef; exports.isNonRetryableError = _chunkKZT3YC62cjs.isNonRetryableError; exports.isValidCredId = _chunkKZT3YC62cjs.isValidCredId; exports.isValidISO8601 = _chunkKZT3YC62cjs.isValidISO8601; exports.isValidTimeZoneId = _chunkKZT3YC62cjs.isValidTimeZoneId; exports.isValidUUID = _chunkKZT3YC62cjs.isValidUUID; exports.isValidUUIDv4 = _chunkKZT3YC62cjs.isValidUUIDv4; exports.isValidUrl = _chunkKZT3YC62cjs.isValidUrl; exports.measurePushPayload = _chunkKZT3YC62cjs.measurePushPayload; exports.nextFutureOccurrence = _chunkKZT3YC62cjs.nextFutureOccurrence; exports.planNextOccurrence = _chunkKZT3YC62cjs.planNextOccurrence; exports.readRequestBody = _chunkKZT3YC62cjs.readRequestBody; exports.resolveLlmCredential = _chunkKZT3YC62cjs.resolveLlmCredential; exports.runScheduledTick = _chunkKZT3YC62cjs.runScheduledTick; exports.runTask = _chunkKZT3YC62cjs.runTask; exports.sanitizeErrorSummary = _chunkKZT3YC62cjs.sanitizeErrorSummary; exports.summarizeErrorCause = _chunkKZT3YC62cjs.summarizeErrorCause; exports.supportsLlmCredentialsStore = _chunkKZT3YC62cjs.supportsLlmCredentialsStore; exports.validateAvatarUrl = _chunkKZT3YC62cjs.validateAvatarUrl; exports.validateCredRefs = _chunkKZT3YC62cjs.validateCredRefs; exports.validateCredValue = _chunkKZT3YC62cjs.validateCredValue; exports.validateLlmMessagesArray = _chunkKZT3YC62cjs.validateLlmMessagesArray; exports.validateScheduleMessagePayload = _chunkKZT3YC62cjs.validateScheduleMessagePayload; exports.validateSplitPattern = _chunkKZT3YC62cjs.validateSplitPattern; exports.verifyTenantToken = verifyTenantToken;
+
+exports.CORS_ALLOW_HEADERS = _chunkAM2MMY46cjs.CORS_ALLOW_HEADERS; exports.CORS_ALLOW_METHODS = _chunkAM2MMY46cjs.CORS_ALLOW_METHODS; exports.CRED_ID_MAX_LENGTH = _chunkAM2MMY46cjs.CRED_ID_MAX_LENGTH; exports.CRED_PUT_BATCH_MAX = _chunkAM2MMY46cjs.CRED_PUT_BATCH_MAX; exports.CRED_REFS_MAX_ENTRIES = _chunkAM2MMY46cjs.CRED_REFS_MAX_ENTRIES; exports.CRED_ROWS_PER_USER_MAX = _chunkAM2MMY46cjs.CRED_ROWS_PER_USER_MAX; exports.DEFAULT_CLAIM_LEASE_MS = _chunkAM2MMY46cjs.DEFAULT_CLAIM_LEASE_MS; exports.DEFAULT_HEARTBEAT_LEASE_TTL_MS = _chunkAM2MMY46cjs.DEFAULT_HEARTBEAT_LEASE_TTL_MS; exports.DEFAULT_LEASE_HEARTBEAT_MS = _chunkAM2MMY46cjs.DEFAULT_LEASE_HEARTBEAT_MS; exports.DEFAULT_MAX_DELIVERY_RETRIES = _chunkAM2MMY46cjs.DEFAULT_MAX_DELIVERY_RETRIES; exports.DEFAULT_MAX_REQUEST_BODY_BYTES = _chunkAM2MMY46cjs.DEFAULT_MAX_REQUEST_BODY_BYTES; exports.DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE = _chunkAM2MMY46cjs.DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE; exports.DEFAULT_MAX_TOOL_ITERATIONS = _chunkAM2MMY46cjs.DEFAULT_MAX_TOOL_ITERATIONS; exports.DEFAULT_TOTAL_TIMEOUT_MS = _chunkAM2MMY46cjs.DEFAULT_TOTAL_TIMEOUT_MS; exports.DeploymentConfigError = _chunkAM2MMY46cjs.DeploymentConfigError; exports.MAX_DEFER_AFTER_MS = _chunkAM2MMY46cjs.MAX_DEFER_AFTER_MS; exports.MAX_PUSH_PAYLOAD_BYTES = _chunkAM2MMY46cjs.MAX_PUSH_PAYLOAD_BYTES; exports.MAX_TASK_PAYLOAD_BYTES = _chunkAM2MMY46cjs.MAX_TASK_PAYLOAD_BYTES; exports.MIN_SCHEDULE_LEAD_MS = _chunkAM2MMY46cjs.MIN_SCHEDULE_LEAD_MS; exports.NonRetryableError = _chunkAM2MMY46cjs.NonRetryableError; exports.PUSH_ENVELOPE_RESERVED_BYTES = _chunkAM2MMY46cjs.PUSH_ENVELOPE_RESERVED_BYTES; exports.SCHEMA_VERSION = _chunkAM2MMY46cjs.SCHEMA_VERSION; exports.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES = _chunkAM2MMY46cjs.WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES; exports.WEB_PUSH_MAX_BODY_BYTES = _chunkAM2MMY46cjs.WEB_PUSH_MAX_BODY_BYTES; exports.advanceOccurrence = _chunkAM2MMY46cjs.advanceOccurrence; exports.createAdapter = createAdapter; exports.createD1Adapter = _chunkAM2MMY46cjs.createD1Adapter; exports.createReiServer = createReiServer; exports.createSingleUserCloudflareWorker = _chunkAM2MMY46cjs.createSingleUserCloudflareWorker; exports.createSingleUserServer = _chunkAM2MMY46cjs.createSingleUserServer; exports.createTenantToken = createTenantToken; exports.createWebCryptoWebPush = _chunkAM2MMY46cjs.createWebCryptoWebPush; exports.decryptFromStorage = _chunkAM2MMY46cjs.decryptFromStorage; exports.decryptPayload = _chunkAM2MMY46cjs.decryptPayload; exports.deriveUserEncryptionKey = _chunkAM2MMY46cjs.deriveUserEncryptionKey; exports.encryptForStorage = _chunkAM2MMY46cjs.encryptForStorage; exports.ensureSchema = _chunkAM2MMY46cjs.ensureSchema; exports.getSchemaVersion = _chunkAM2MMY46cjs.getSchemaVersion; exports.hasChatCredRef = _chunkAM2MMY46cjs.hasChatCredRef; exports.isNonRetryableError = _chunkAM2MMY46cjs.isNonRetryableError; exports.isValidCredId = _chunkAM2MMY46cjs.isValidCredId; exports.isValidISO8601 = _chunkAM2MMY46cjs.isValidISO8601; exports.isValidTimeZoneId = _chunkAM2MMY46cjs.isValidTimeZoneId; exports.isValidUUID = _chunkAM2MMY46cjs.isValidUUID; exports.isValidUUIDv4 = _chunkAM2MMY46cjs.isValidUUIDv4; exports.isValidUrl = _chunkAM2MMY46cjs.isValidUrl; exports.measurePushPayload = _chunkAM2MMY46cjs.measurePushPayload; exports.nextFutureOccurrence = _chunkAM2MMY46cjs.nextFutureOccurrence; exports.planNextOccurrence = _chunkAM2MMY46cjs.planNextOccurrence; exports.readRequestBody = _chunkAM2MMY46cjs.readRequestBody; exports.resolveLlmCredential = _chunkAM2MMY46cjs.resolveLlmCredential; exports.runScheduledTick = _chunkAM2MMY46cjs.runScheduledTick; exports.runTask = _chunkAM2MMY46cjs.runTask; exports.sanitizeErrorSummary = _chunkAM2MMY46cjs.sanitizeErrorSummary; exports.summarizeErrorCause = _chunkAM2MMY46cjs.summarizeErrorCause; exports.supportsLlmCredentialsStore = _chunkAM2MMY46cjs.supportsLlmCredentialsStore; exports.validateAvatarUrl = _chunkAM2MMY46cjs.validateAvatarUrl; exports.validateCredRefs = _chunkAM2MMY46cjs.validateCredRefs; exports.validateCredValue = _chunkAM2MMY46cjs.validateCredValue; exports.validateLlmMessagesArray = _chunkAM2MMY46cjs.validateLlmMessagesArray; exports.validateScheduleMessagePayload = _chunkAM2MMY46cjs.validateScheduleMessagePayload; exports.validateSplitPattern = _chunkAM2MMY46cjs.validateSplitPattern; exports.verifyTenantToken = verifyTenantToken;

package/dist/index.d.cts

@@ -175,7 +175,7 @@ export type ReiServer = {
 export { runScheduledTick, runTask, DEFAULT_CLAIM_LEASE_MS, DEFAULT_LEASE_HEARTBEAT_MS, DEFAULT_HEARTBEAT_LEASE_TTL_MS, DEFAULT_MAX_DELIVERY_RETRIES, sanitizeErrorSummary } from "./lib/run-tick.js";
 export { NonRetryableError, DeploymentConfigError, isNonRetryableError, summarizeErrorCause } from "./lib/errors.js";
 export { getSchemaVersion, ensureSchema, SCHEMA_VERSION } from "./lib/schema-version.js";
-export { DEFAULT_MAX_TOOL_ITERATIONS, DEFAULT_TOTAL_TIMEOUT_MS, DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE, MIN_SCHEDULE_LEAD_MS } from "./lib/agentic-fire.js";
+export { DEFAULT_MAX_TOOL_ITERATIONS, DEFAULT_TOTAL_TIMEOUT_MS, DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE, MIN_SCHEDULE_LEAD_MS, MAX_DEFER_AFTER_MS } from "./lib/agentic-fire.js";
 export { CORS_ALLOW_HEADERS, CORS_ALLOW_METHODS, createSingleUserCloudflareWorker } from "./cloudflare/single-user-worker.js";
 export { createWebCryptoWebPush, measurePushPayload, MAX_PUSH_PAYLOAD_BYTES, PUSH_ENVELOPE_RESERVED_BYTES, WEB_PUSH_MAX_BODY_BYTES, WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES } from "./lib/webpush-webcrypto.js";
 export { deriveUserEncryptionKey, decryptPayload, encryptForStorage, decryptFromStorage } from "./lib/encryption.js";

package/dist/index.d.ts

@@ -175,7 +175,7 @@ export type ReiServer = {
 export { runScheduledTick, runTask, DEFAULT_CLAIM_LEASE_MS, DEFAULT_LEASE_HEARTBEAT_MS, DEFAULT_HEARTBEAT_LEASE_TTL_MS, DEFAULT_MAX_DELIVERY_RETRIES, sanitizeErrorSummary } from "./lib/run-tick.js";
 export { NonRetryableError, DeploymentConfigError, isNonRetryableError, summarizeErrorCause } from "./lib/errors.js";
 export { getSchemaVersion, ensureSchema, SCHEMA_VERSION } from "./lib/schema-version.js";
-export { DEFAULT_MAX_TOOL_ITERATIONS, DEFAULT_TOTAL_TIMEOUT_MS, DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE, MIN_SCHEDULE_LEAD_MS } from "./lib/agentic-fire.js";
+export { DEFAULT_MAX_TOOL_ITERATIONS, DEFAULT_TOTAL_TIMEOUT_MS, DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE, MIN_SCHEDULE_LEAD_MS, MAX_DEFER_AFTER_MS } from "./lib/agentic-fire.js";
 export { CORS_ALLOW_HEADERS, CORS_ALLOW_METHODS, createSingleUserCloudflareWorker } from "./cloudflare/single-user-worker.js";
 export { createWebCryptoWebPush, measurePushPayload, MAX_PUSH_PAYLOAD_BYTES, PUSH_ENVELOPE_RESERVED_BYTES, WEB_PUSH_MAX_BODY_BYTES, WEB_PUSH_ENCRYPTION_OVERHEAD_BYTES } from "./lib/webpush-webcrypto.js";
 export { deriveUserEncryptionKey, decryptPayload, encryptForStorage, decryptFromStorage } from "./lib/encryption.js";

package/dist/index.mjs

@@ -14,6 +14,7 @@ import {
   DEFAULT_MAX_TOOL_ITERATIONS,
   DEFAULT_TOTAL_TIMEOUT_MS,
   DeploymentConfigError,
+  MAX_DEFER_AFTER_MS,
   MAX_PUSH_PAYLOAD_BYTES,
   MAX_TASK_PAYLOAD_BYTES,
   MIN_SCHEDULE_LEAD_MS,
@@ -72,7 +73,7 @@ import {
   validateLlmMessagesArray,
   validateScheduleMessagePayload,
   validateSplitPattern
-} from "./chunk-INNZZFGJ.mjs";
+} from "./chunk-Q4VQ3NVR.mjs";
 import "./chunk-GN44PST5.mjs";
 
 // src/server/adapters/factory.js
@@ -654,6 +655,7 @@ export {
   DEFAULT_MAX_TOOL_ITERATIONS,
   DEFAULT_TOTAL_TIMEOUT_MS,
   DeploymentConfigError,
+  MAX_DEFER_AFTER_MS,
   MAX_PUSH_PAYLOAD_BYTES,
   MAX_TASK_PAYLOAD_BYTES,
   MIN_SCHEDULE_LEAD_MS,

package/dist/lib/agentic-fire.d.ts

@@ -57,12 +57,18 @@ export function buildHookTask(task: any, decryptedPayload: any): Readonly<{
  * @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, maxScheduledTasksPerFire })
- * @returns {Promise<{ handled: false } | { handled: true, result: { success: true, messagesSent: number, status: 'finished'|'skipped', iterations: number } }>}
+ * @returns {Promise<{ handled: false }
+ *   | { handled: true, result: { success: true, messagesSent: number, status: 'finished'|'skipped', iterations: number } }
+ *   | { handled: true, result: { success: false, deferred: true, retryAfter: string, messagesSent: 0, status: 'deferred', iterations: 0 } }>}
  *   `handled: false` → caller falls back to the legacy frozen-prompt path
  *   (onBeforeFire returned null).
  *   `onBeforeFire` may also return `{ skip: true }` to complete the fire
  *   before the first LLM call → `status: 'skipped', iterations: 0`, same
  *   success handling as the post-LLM skip-push path.
+ *   `{ defer: { afterMs } }` → `status: 'deferred'`，`retryAfter` 是「什么时候
+ *   再来问」的 ISO 时刻。`success` 给 false 而不是 true：这次什么都没发，调用
+ *   方得看 `deferred` 走推迟的收尾；万一有调用方不认识这个字段，也只会把它当
+ *   成没发成，不会当成发完了把任务删掉。
  *   Failures (timeout / loop exceeded / config errors) throw — the caller's
  *   existing error handling turns them into task retry/failure.
  *
@@ -84,6 +90,16 @@ export function runAgenticFire({ task, decryptedPayload, userKey, ctx }: {
         status: "finished" | "skipped";
         iterations: number;
     };
+} | {
+    handled: true;
+    result: {
+        success: false;
+        deferred: true;
+        retryAfter: string;
+        messagesSent: 0;
+        status: "deferred";
+        iterations: 0;
+    };
 }>;
 /**
  * 把这一轮的 usage 累加进整次 fire 的合计，返回新的合计（不改传入的对象）。
@@ -116,6 +132,32 @@ export const DEFAULT_MAX_TOOL_ITERATIONS: 5;
 export const DEFAULT_TOTAL_TIMEOUT_MS: 240000;
 export const DEFAULT_MAX_SCHEDULED_TASKS_PER_FIRE: 2;
 export const MIN_SCHEDULE_LEAD_MS: 60000;
+export const MAX_DEFER_AFTER_MS: number;
+/**
+ * - 消息数组 / `{ messages, ... }`：用这份 prompt 生成；
+ * - `{ skip: true }`：这次不发，按零推送的成功收场（一次性任务删行、循环任务
+ * 推进到下一次）；
+ * - `{ defer: { afterMs } }`：现在不合适，afterMs 毫秒后再来问。afterMs 必须
+ * 是有限正数，且不超过 MAX_DEFER_AFTER_MS（24 小时）；
+ * - `null` / `undefined`：交还给排程时冻结的 prompt 老链路。
+ */
+export type BeforeFireResult = Array<any> | {
+    messages: Array<any>;
+    maxToolIterations?: number;
+    totalTimeoutMs?: number;
+    tools?: Array<any>;
+    toolChoice?: any;
+} | {
+    skip: true;
+} | {
+    defer: {
+        afterMs: number;
+    };
+} | null | undefined;
+/**
+ * 收尾回执（onFireSettled）的 status。
+ */
+export type FireSettledStatus = "sent" | "skipped" | "deferred" | "failed" | "cancelled" | "not-handled";
 /**
  * 把任务的调度身份投影进一条 push。
  *

package/dist/lib/message-processor.d.ts

@@ -9,8 +9,11 @@
  * @param {string} [providedMasterKey]
  * @param {{ userKey: string, payload: Object } | null} [predecrypted] - 调用方
  *   （run-tick 的预扫描）已经解好的 payload；传了就不再解第二遍。
- * @returns {Promise<{ success: boolean, messagesSent: number, redelivered?: boolean, pushedCount?: number, error?: string, errorCode?: string|null, pushStatusCode?: number|null, permanent?: boolean, willRetry?: boolean, retryLimit?: number, failureStage?: string }>}
+ * @returns {Promise<{ success: boolean, messagesSent: number, redelivered?: boolean, pushedCount?: number, deferred?: boolean, retryAfter?: string, error?: string, errorCode?: string|null, pushStatusCode?: number|null, permanent?: boolean, willRetry?: boolean, retryLimit?: number, failureStage?: string }>}
  *   失败时 `pushStatusCode` 是推送服务回的 HTTP 状态码（不是推送阶段炸的 → null）。
+ *   `deferred: true` 表示 onBeforeFire 把这次触发推迟了（`retryAfter` 是唤醒
+ *   时刻）：`success` 为 false 但不是失败，调用方要先看这个字段。只有 ctx 带
+ *   `_deferSupported: true`（run-tick 在适配器有 retry_after 列时给）才会出现。
  */
 export function processSingleMessage(task: import("../adapters/interface.js").TaskRow, ctx: ProcessorContext, providedMasterKey?: string, predecrypted?: {
     userKey: string;
@@ -20,6 +23,8 @@ export function processSingleMessage(task: import("../adapters/interface.js").Ta
     messagesSent: number;
     redelivered?: boolean;
     pushedCount?: number;
+    deferred?: boolean;
+    retryAfter?: string;
     error?: string;
     errorCode?: string | null;
     pushStatusCode?: number | null;
@@ -40,6 +45,9 @@ export function processSingleMessage(task: import("../adapters/interface.js").Ta
  *   `reasoningError` 只在正文都发出去了、思考过程那一条没发成时出现（思考过程是
  *   附赠内容，它发不出去不算这条消息失败）。调用方拿它提示用户这次没有思考过程，
  *   不带这个字段就是整轮都送到了。
+ *
+ *   这条路是请求里当场投递，不支持 onBeforeFire 的 `{ defer }`：返回它会得到
+ *   AGENTIC_DEFER_UNSUPPORTED 的配置错误，按这里的失败流程处理。
  */
 export function processMessagesByUuid(uuid: string, ctx: ProcessorContext, maxRetries?: number, userId?: string, providedMasterKey?: string): Promise<{
     success: boolean;

package/dist/lib/run-tick.d.ts

@@ -24,6 +24,7 @@ export function runScheduledTick(ctx: any): Promise<{
         deletedOnceOffTasks: number;
         updatedRecurringTasks: number;
         staleTasks: any[];
+        deferredTasks: any[];
         cancelledTasks: any[];
         reasoningSkippedTasks: any[];
         redeliveredTasks: any[];
@@ -45,8 +46,11 @@ export function runScheduledTick(ctx: any): Promise<{
  *   - `already_settled`：行还在，但已经是 sent / failed（`status` 带上是哪
  *     个）。适配器没实现 `getTaskStatusByUuidOnly` 时这种情况并进 `not_found`。
  *   - `not_due`：还没到 `next_send_at`（`nextSendAt` 带上是什么时候）。
- *   - `retry_pending`：上次投递失败，还在退避窗口里（`retryAfter` 带上什么时
- *     候到点）。
+ *   - `retry_pending`：上次投递失败还在退避窗口里，或者上次 onBeforeFire 把
+ *     它推迟了（`{ defer }`）还没到点（`retryAfter` 带上什么时候到点）。
+ *
+ * 这一次跑的时候 onBeforeFire 返回 `{ defer }` 的话，结果是 `ran: true`，任务
+ * 列在 summary.details.deferredTasks 里；到点之前再调都回 `retry_pending`。
  *
  * @param {Object} ctx - 与 runScheduledTick 同一份 ctx
  * @param {string} uuid - 任务 uuid（pending 行）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rei-standard/amsg-server",
-  "version": "2.6.0-next.32",
+  "version": "2.6.0-next.33",
   "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",