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

package/README.md

@@ -703,6 +703,26 @@ LLM 这一条只认上游**答复了、并且拒了**的那几种状态码：Key
 
 `GET /capabilities` 的 features 里对应 `llm-permanent-errors`、`redeliver-committed-batch`、`hook-usage-total`、`max-delivery-retries`。
 
+## 按任务限制生成重试（`maxGenerationRetries`）
+
+用户主动触发的回复可以第一次生成失败就结束，定时任务则保留默认退避。工厂配置和 `runScheduledTick` / `runTask` 支持 `maxGenerationRetries`，值可以是非负整数，也可以是同步函数：
+
+```js
+createSingleUserCloudflareWorker((env) => ({
+  // 这里的 interactive 是宿主自己约定的 metadata，库不认识业务类型。
+  maxGenerationRetries: (task) => task.metadata?.interactive ? 0 : undefined,
+  // ...其余配置
+}));
+```
+
+回调收到与 `serializeBy` 相同的安全任务视图（含 metadata，不含 API Key 等凭据），每次尝试解析一次。返回 `undefined` 继承 `maxDeliveryRetries`（默认 3），返回 0 禁止本轮失败后重新生成；显式数值单独控制生成重试上限。不配置时行为不变，不需要修改任务 payload 或迁移数据库，已有任务也生效。所有服务端工厂和旧的 UUID 即时入口都透传这个配置。
+
+这里的“生成阶段”以**最终回复整批进入 outbox**为边界：前置 hook、模型、工具循环、组装和落库失败都使用生成上限；没有 outbox 的适配器发生推送失败时仍可能需要重新生成，因此也使用生成上限。完整批次已入 outbox 后的推送失败改用 `maxDeliveryRetries`，补投不会再次调用模型。hook 的独立 `emitResult` 不等于最终回复提交。
+
+`onFireSettled` 新增 `willRetry` 与 `failureStage`：失败时前者为本次的重试决策，后者为 `'generation'` 或 `'delivery'`；成功、跳过、未接管时两者均为 `null`。宿主可以用 `info.status === 'failed' && info.willRetry === false && !info.outboxed` 即时显示生成失败，无需修改错误对象或猜测重试次数。此回执发生在调度器写任务状态之前，`willRetry` 描述同源策略决策，不保证后续数据库写入成功；取消导致的失败不会重试。已有永久性错误判定仍然生效。
+
+策略回调抛错或返回非法值时，不调用生成 hook / 模型，以 `GENERATION_RETRY_POLICY_INVALID` 记录配置错误并沿默认投递上限退避，避免一次坏部署立即作废所有任务；此时尚未进入 fire，因此不触发 `onFireSettled`。
+
 ## 同一分组的任务不并发（`serializeBy`）
 
 同一个角色可能有好几条定时任务。撞在一起并发跑的话，用户一口气收到两条互不知情的消息；宿主在 hook 里维护的「我刚才说过什么」台账通常是读进内存 → 改 → 整份写回，两条各改各的再写回，后写的必然盖掉前面那条。
@@ -920,3 +940,30 @@ VERCEL_PROTECTION_BYPASS=YOUR_BYPASS_KEY
 - [SW 包 README](https://github.com/Tosd0/ReiStandard/blob/main/packages/rei-standard-amsg/sw/README.md)
 - [API 技术规范](https://github.com/Tosd0/ReiStandard/blob/main/standards/active-messaging-api.md)
 - [Service Worker 规范](https://github.com/Tosd0/ReiStandard/blob/main/standards/service-worker-specification.md)
+
+
+## 取消正在执行的生成与工具
+
+任务被 `DELETE /cancel-message` 取消或被新任务顶替后，租约心跳发现任务已经失效，会中断正在等待的模型请求，阻止新的模型轮次、工具阶段和推送。`leaseHeartbeatMs` 默认仍为 30000；需要及时停止的交互应用可配置为 1000（每个正在执行的任务每秒续租一次）。这是跨请求的数据库检测，延迟取决于心跳和数据库响应，不承诺瞬时中断。自定义适配器需要支持 `claimTask` / `renewTaskLease`；关掉心跳时也关掉了这条主动检测路径。
+
+`onBeforeFire`、`onLLMOutput`、`executeToolCalls` 的 context 以及 `onFireSettled` 回执新增：
+
+- `signal: AbortSignal`：传给工具内部的 `fetch`，与工具自己的超时信号合并。
+- `isCancelled(): boolean`：当前是否已收到取消信号。
+- `throwIfCancelled(): void`：已取消时抛出 `code: 'TASK_CANCELLED'` 的错误。每个副作用开始前检查，工具 catch 中也要先调用它，以免取消被转成普通工具失败后继续执行。
+
+```js
+async function executeToolCalls(calls, ctx) {
+  const results = [];
+  for (const call of calls) {
+    ctx.throwIfCancelled();
+    const response = await fetch(toolUrl(call), { signal: ctx.signal });
+    results.push({ tool_call_id: call.id, role: 'tool', content: await response.text() });
+  }
+  return results;
+}
+```
+
+取消收尾使用 `onFireSettled({ status: 'cancelled', willRetry: false, error, ... })`，不是生成失败。应用应在这里释放资源、结算已发生的用量，避免发出失败提示或把未送达内容记为已回复。取消时已经开始写入的 outbox 批次会在写完后检查信号并撤掉未投递部分；已经发到客户端的消息仍由客户端处理。应用需要记录停止的任务身份，拦住迟到推送、补收以及尚未显示的本地内容。已完成的外部副作用无法撤销；不支持 AbortSignal 的工具也需要自己在执行步骤之间检查取消。
+
+执行阶段的 `ctx.writeState`、`scheduleTask`、`cancelTask`、`renewTask` 和 `emitResult` 会拒绝取消后新发起的操作。`onFireSettled` 的 `info.writeState` 特意仍可用，供宿主释放锁、保存账单等收尾；它不能用于继续生成阶段的业务动作。已经开始的数据库写入不支持回滚，宿主仍需处理并发状态版本。

package/dist/adapters/d1.d.ts

@@ -110,6 +110,15 @@ export class D1Adapter {
         status: string;
     } | null>;
     updateTaskById(taskId: any, updates: any): Promise<any>;
+    /**
+     * 按 uuid 改一条 pending 任务（PUT /update-message、fire hook 的 renewTask）。
+     *
+     * 改排期（extraFields 里带 next_send_at）时多一道租约门：这条任务正被一次投递
+     * 占着的话不改，返回 null。投递收尾会按自己领取时看到的排期推进下一次（一次性
+     * 任务干脆标成已发送），这期间写进去的新时刻随后就被盖掉，接口却已经回了成功
+     * ——用户以为改期生效了，实际什么都没留下。正文这类字段不受这道门约束：它们
+     * 只影响以后的触发，收尾那边本来就不会覆盖（见 run-tick 的收尾守卫）。
+     */
     updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any): Promise<{
         uuid: any;
         updated_at: string;

package/dist/adapters/interface.d.ts

@@ -302,8 +302,10 @@ export type DbAdapter = {
         last_error: string | null;
     } | null>;
     /**
-     * （可选）建新任务的同一事务里取消旧的那条（POST /schedule-message 的
-     * supersedesUuid）。不实现时 handler 退回「先删再建」两步（失去原子性）。
+     * （可选）建新任务的同时取消旧的那条，两件事一起成败（POST /schedule-message
+     * 的 supersedesUuid）。内置的 D1 / pg / neon 都实现了。不实现时 handler 退回
+     * 两步：先建新、后删旧——删旧失败最坏是两条都留着，客户端重试一次就能收拾，
+     * 而反过来（先删后建）建新失败就把旧任务白删了，找不回来。
      */
     createTaskSuperseding?: (params: InsertTaskParams, supersedesUuid: string) => Promise<TaskRow & {
         superseded: boolean;

package/dist/adapters/neon.d.ts

@@ -39,6 +39,14 @@ export class NeonAdapter {
     }>;
     dropSchema(): Promise<void>;
     createTask(params: any): Promise<Record<string, any>>;
+    createTaskSuperseding(params: any, supersedesUuid: any): Promise<{
+        id: number;
+        uuid: string;
+        next_send_at: any;
+        status: string;
+        created_at: any;
+        superseded: boolean;
+    }>;
     getTaskByUuid(uuid: any, userId: any): Promise<Record<string, any>>;
     getTaskByUuidOnly(uuid: any): Promise<Record<string, any>>;
     /**
@@ -52,6 +60,15 @@ export class NeonAdapter {
         status: string;
     } | null>;
     updateTaskById(taskId: any, updates: any): Promise<Record<string, any>>;
+    /**
+     * 按 uuid 改一条 pending 任务（PUT /update-message、fire hook 的 renewTask）。
+     *
+     * 改排期（extraFields 里带 next_send_at）时多一道租约门：这条任务正被一次投递
+     * 占着的话不改，返回 null。投递收尾会按自己领取时看到的排期推进下一次（一次性
+     * 任务干脆标成已发送），这期间写进去的新时刻随后就被盖掉，接口却已经回了成功
+     * ——用户以为改期生效了，实际什么都没留下。正文这类字段不受这道门约束：它们
+     * 只影响以后的触发，收尾那边本来就不会覆盖（见 run-tick 的收尾守卫）。
+     */
     updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any): Promise<Record<string, any>>;
     deleteTaskById(taskId: any): Promise<boolean>;
     deleteTaskByUuid(uuid: any, userId: any): Promise<boolean>;

package/dist/adapters/pg-shared.d.ts

@@ -59,6 +59,39 @@ export function claimTask(query: PgQuery, taskId: number, expectedNextSendAt: st
  * @returns {Promise<boolean>} true = 续上了
  */
 export function renewTaskLease(query: PgQuery, taskId: number, leaseUntil: string | Date): Promise<boolean>;
+/**
+ * 建新任务的同时把被顶替的旧任务删掉（POST /schedule-message 带
+ * supersedesUuid 时走这条）。
+ *
+ * 删旧和建新必须一起成败：分成两次查询的话，建新那步失败（uuid 撞了、连接
+ * 一时抖了）时旧任务已经删掉了，接口却回失败——客户端以为旧任务还在，实际
+ * 上它已经没了，没有任何办法找回来。
+ *
+ * 一条语句解决，不用显式事务：数据修改型 CTE 里的 DELETE 一定会执行到底，
+ * 而 INSERT 抛错时整条语句一起回滚（pg 与 neon 的 HTTP 驱动都是单语句一个
+ * 隐式事务，用法完全一致）。superseded 由 DELETE 到底删没删到行推出来。
+ *
+ * @param {PgQuery} query
+ * @param {{ user_id: string, uuid: string, encrypted_payload: string,
+ *   next_send_at: string|Date, message_type: string }} params - 新任务
+ * @param {string} supersedesUuid - 要顶替掉的旧任务 uuid（同一个用户名下）
+ * @returns {Promise<{ id: number, uuid: string, next_send_at: any, status: string,
+ *   created_at: any, superseded: boolean }|null>}
+ */
+export function createTaskSuperseding(query: PgQuery, params: {
+    user_id: string;
+    uuid: string;
+    encrypted_payload: string;
+    next_send_at: string | Date;
+    message_type: string;
+}, supersedesUuid: string): Promise<{
+    id: number;
+    uuid: string;
+    next_send_at: any;
+    status: string;
+    created_at: any;
+    superseded: boolean;
+} | null>;
 /**
  * 状态 + 失败摘要（GET /message 用它把「为什么失败」透给已失败的行）。
  *

package/dist/adapters/pg.d.ts

@@ -35,6 +35,14 @@ export class PgAdapter {
     }>;
     dropSchema(): Promise<void>;
     createTask(params: any): Promise<any[]>;
+    createTaskSuperseding(params: any, supersedesUuid: any): Promise<{
+        id: number;
+        uuid: string;
+        next_send_at: any;
+        status: string;
+        created_at: any;
+        superseded: boolean;
+    }>;
     getTaskByUuid(uuid: any, userId: any): Promise<any[]>;
     getTaskByUuidOnly(uuid: any): Promise<any[]>;
     /**
@@ -48,6 +56,15 @@ export class PgAdapter {
         status: string;
     } | null>;
     updateTaskById(taskId: any, updates: any): Promise<any[]>;
+    /**
+     * 按 uuid 改一条 pending 任务（PUT /update-message、fire hook 的 renewTask）。
+     *
+     * 改排期（extraFields 里带 next_send_at）时多一道租约门：这条任务正被一次投递
+     * 占着的话不改，返回 null。投递收尾会按自己领取时看到的排期推进下一次（一次性
+     * 任务干脆标成已发送），这期间写进去的新时刻随后就被盖掉，接口却已经回了成功
+     * ——用户以为改期生效了，实际什么都没留下。正文这类字段不受这道门约束：它们
+     * 只影响以后的触发，收尾那边本来就不会覆盖（见 run-tick 的收尾守卫）。
+     */
     updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any): Promise<any[]>;
     deleteTaskById(taskId: any): Promise<boolean>;
     deleteTaskByUuid(uuid: any, userId: any): Promise<boolean>;