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

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）。
 
@@ -967,3 +1014,18 @@ async function executeToolCalls(calls, ctx) {
 取消收尾使用 `onFireSettled({ status: 'cancelled', willRetry: false, error, ... })`，不是生成失败。应用应在这里释放资源、结算已发生的用量，避免发出失败提示或把未送达内容记为已回复。取消时已经开始写入的 outbox 批次会在写完后检查信号并撤掉未投递部分；已经发到客户端的消息仍由客户端处理。应用需要记录停止的任务身份，拦住迟到推送、补收以及尚未显示的本地内容。已完成的外部副作用无法撤销；不支持 AbortSignal 的工具也需要自己在执行步骤之间检查取消。
 
 执行阶段的 `ctx.writeState`、`scheduleTask`、`cancelTask`、`renewTask` 和 `emitResult` 会拒绝取消后新发起的操作。`onFireSettled` 的 `info.writeState` 特意仍可用，供宿主释放锁、保存账单等收尾；它不能用于继续生成阶段的业务动作。已经开始的数据库写入不支持回滚，宿主仍需处理并发状态版本。
+
+### Cloud data inventory and cleanup (D1)
+
+Single-user D1 deployments expose `cloud-data-management` in `/capabilities`.
+The management API lists actual cloud resources, including acknowledged outbox
+rows, orphan state chunks and resources missing a local character. Cleanup uses
+server previews, persistent operations and cron continuation. Owner retirement
+fences future writes and in-flight task outputs; restoration is explicit and
+returns the generation required on subsequent writes.
+
+See the repository [cloud data management contract](../../../docs/cloud-data-management.md)
+for routes, encrypted metadata, host `cloudData.resolveOwner` configuration,
+retention, and upgrade requirements. Other adapters do not advertise this
+capability. Use the matching client SDK management methods rather than composing
+bulk deletes from the browser's local resource list.

package/dist/adapters/d1.d.ts

@@ -49,6 +49,81 @@ export class D1Adapter {
      * @returns {Promise<number>} 各批影响行数之和
      */
     private _runInClauseWrite;
+    /** A complete management implementation needs real transactional batches. */
+    get cloudDataManagement(): boolean;
+    _cloudGuardPredicate(userId: any, guard: any): {
+        sql: string;
+        args: any[];
+    };
+    _cloudBatch(statements: any, userId: any, guards?: any[], metadata?: Map<any, any>): Promise<any[]>;
+    getCloudResourceMetadata(userId: any, resourceKey: any): Promise<any>;
+    listCloudResourceRows(userId: any): Promise<{
+        gaps: any[];
+    }>;
+    _cloudRecord(row: any): Promise<{
+        id: any;
+        userId: any;
+        kind: any;
+        data: any;
+        updatedAt: any;
+    }>;
+    putCloudDataRecord(userId: any, kind: any, id: any, data: any, { idempotencyKey, createOnly, leaseToken }?: {
+        idempotencyKey?: any;
+        createOnly?: boolean;
+    }): Promise<{
+        id: any;
+        userId: any;
+        kind: any;
+        data: any;
+        updatedAt: any;
+    }>;
+    getCloudDataRecord(userId: any, kind: any, id: any): Promise<{
+        id: any;
+        userId: any;
+        kind: any;
+        data: any;
+        updatedAt: any;
+    }>;
+    getCloudDataRecordByIdempotency(userId: any, kind: any, idempotencyKey: any): Promise<{
+        id: any;
+        userId: any;
+        kind: any;
+        data: any;
+        updatedAt: any;
+    }>;
+    _cloudRecordForList(row: any): Promise<{
+        id: any;
+        userId: any;
+        kind: any;
+        data: any;
+        updatedAt: any;
+    }>;
+    listCloudDataRecords(userId: any, kind: any): Promise<any[]>;
+    listCloudDataRecordsAcrossUsers(kind: any): Promise<any[]>;
+    claimCloudDataRecord(userId: any, kind: any, id: any, leaseMs: any, leaseToken?: any): Promise<boolean>;
+    releaseCloudDataRecord(userId: any, kind: any, id: any, leaseToken: any): Promise<void>;
+    renewCloudDataRecordLease(userId: any, kind: any, id: any, leaseMs: any, leaseToken: any): Promise<boolean>;
+    deleteCloudDataRecord(userId: any, kind: any, id: any): Promise<boolean>;
+    cleanupCloudDataRecords(kind: any, beforeMs: any): Promise<any>;
+    /** Sidecars are indexes only. Remove them only while their backing row is absent. */
+    cleanupCloudResourceMetadata(userId?: any): Promise<any>;
+    listCloudOwners(userId: any): Promise<any>;
+    getCloudOwner(userId: any, owner: any): Promise<{
+        active: boolean;
+        generation: any;
+        updatedAt: any;
+    }>;
+    setCloudOwnerActive(userId: any, owner: any, active: any, expectedGeneration: any): Promise<{
+        active: boolean;
+        generation: any;
+        updatedAt: any;
+    }>;
+    isCloudOwnerGuardValid(userId: any, guard: any): Promise<boolean>;
+    /** Delete only the exact physical snapshot; no untrusted SQL identifiers. */
+    deleteCloudResourceRows(userId: any, locators: any, { operationId, leaseToken }?: {}): Promise<{
+        deleted: number;
+        changed: number;
+    }>;
     initSchema(): Promise<{
         columnsCreated: number;
         indexesCreated: number;
@@ -83,7 +158,7 @@ export class D1Adapter {
         indexes: string[];
     }>;
     dropSchema(): Promise<void>;
-    createTask(params: any): Promise<any>;
+    createTask(params: any, cloudGuard?: any): Promise<any>;
     /**
      * 建新任务的同时取消旧的那条（`POST /schedule-message` 的 supersedesUuid）。
      *
@@ -96,7 +171,7 @@ export class D1Adapter {
      * @returns {Promise<Object>} createTask 的返回行 + `superseded`（旧行是否
      *   真的被删掉；false = 旧行本就不存在）
      */
-    createTaskSuperseding(params: import("./interface.js").InsertTaskParams, supersedesUuid: string): Promise<any>;
+    createTaskSuperseding(params: import("./interface.js").InsertTaskParams, supersedesUuid: string, cloudGuard?: any): Promise<any>;
     getTaskByUuid(uuid: any, userId: any): Promise<any>;
     getTaskByUuidOnly(uuid: any): Promise<any>;
     /**
@@ -109,7 +184,7 @@ export class D1Adapter {
     getTaskStatusByUuidOnly(uuid: string): Promise<{
         status: string;
     } | null>;
-    updateTaskById(taskId: any, updates: any): Promise<any>;
+    updateTaskById(taskId: any, updates: any, cloudGuard?: any): Promise<any>;
     /**
      * 按 uuid 改一条 pending 任务（PUT /update-message、fire hook 的 renewTask）。
      *
@@ -119,7 +194,7 @@ export class D1Adapter {
      * ——用户以为改期生效了，实际什么都没留下。正文这类字段不受这道门约束：它们
      * 只影响以后的触发，收尾那边本来就不会覆盖（见 run-tick 的收尾守卫）。
      */
-    updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any): Promise<{
+    updateTaskByUuid(uuid: any, userId: any, encryptedPayload: any, extraFields: any, cloudGuard?: any): Promise<{
         uuid: any;
         updated_at: string;
     }>;
@@ -160,7 +235,7 @@ export class D1Adapter {
      * @returns {Promise<boolean>} true = 领到了；false = 别人正拿着租约、同分组
      *   有任务正在跑、排期被改过、或行已不是 pending
      */
-    claimTask(taskId: number, expectedNextSendAt: string, leaseUntil: string | Date, serializeGroup?: string | null): Promise<boolean>;
+    claimTask(taskId: number, expectedNextSendAt: string, leaseUntil: string | Date, serializeGroup?: string | null, cloudGuard?: any): Promise<boolean>;
     /**
      * 投递期间的租约续期（run-tick 的心跳用）。只在行仍是 pending 且确实持有
      * 租约（lease_until 非空）时生效——收尾把租约放掉之后，迟到的心跳不会把
@@ -170,7 +245,7 @@ export class D1Adapter {
      * @param {string|Date} leaseUntil - 新的租期末尾
      * @returns {Promise<boolean>} true = 续上了
      */
-    renewTaskLease(taskId: number, leaseUntil: string | Date): Promise<boolean>;
+    renewTaskLease(taskId: number, leaseUntil: string | Date, cloudGuard?: any): Promise<boolean>;
     listTasks(userId: any, opts?: {}): Promise<{
         tasks: any;
         total: number;
@@ -241,7 +316,7 @@ export class D1Adapter {
         key?: string;
         keyPrefix?: string;
         updatedAt: number;
-    }>, now?: number): Promise<{
+    }>, now?: number, cloudGuard?: any): Promise<{
         upserted: number;
         skipped: number;
         outcomes: boolean[];
@@ -377,7 +452,7 @@ export class D1Adapter {
     upsertLlmCredentials(userId: string, entries: Array<{
         credId: string;
         encryptedValue: string;
-    }>): Promise<number>;
+    }>, cloudGuard?: any): Promise<number>;
     /**
      * 按 cred_id 批量读这个用户的凭据行（`encrypted_value` 是密文，解密在上
      * 层）。排程时的存在性检查和 fire 时的解析共用这一个口。
@@ -456,7 +531,7 @@ export class D1Adapter {
         total_messages?: number | null;
         payload: string;
         created_at: number;
-    }>): Promise<number>;
+    }>, cloudGuard?: any): Promise<number>;
     /**
      * 把这一批标记为「Web Push 已发出」。发送失败的段不标——delivered_at 为
      * null 的行正是客户端最需要拉的那部分。

package/dist/adapters/schema.sqlite.d.ts

@@ -53,6 +53,7 @@ export const SQLITE_ALL_INDEXES: {
     description: string;
     critical: boolean;
 }[];
+export const CLOUD_DATA_TABLES_SQL: string[];
 /**
  * 这一版代码跑起来需要的表 / 列 / 索引。
  *