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

package/dist/lib/outbox-store.d.ts

@@ -0,0 +1,162 @@
+/** 适配器支持 outbox 吗（写入侧要用的两个方法都在才算）。 */
+export function supportsOutbox(db: any): boolean;
+/**
+ * 发送前把这一批 push 落进 outbox。push 对象须已定稿（messageId / sessionId /
+ * messageIndex / totalMessages / 任务身份都已补齐）——落进去的密文就是客户端
+ * 补收时拿到的那一份。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {CryptoKey|string} args.userKey - per-user 存储密钥
+ * @param {Object[]} args.pushes - 定稿后的 push 对象
+ * @returns {Promise<boolean>} 是否真的落了行（适配器不支持 / 落行失败 → false）
+ */
+export function appendPushesToOutbox({ db, userId, userKey, pushes }: {
+    db: any;
+    userId: string;
+    userKey: CryptoKey | string;
+    pushes: any[];
+}): Promise<boolean>;
+/**
+ * 把 push 对象转成 message_outbox 的行（payload 加密）。
+ *
+ * 抽出来是给 `ctx.emitResult()` 用的：它落的行要跟推送链路落的完全同构——
+ * 列一样、加密方式一样、身份字段的取法一样，客户端补收时才不用区分是谁写的。
+ *
+ * @param {Object[]} pushes - 定稿后的 push 对象
+ * @param {CryptoKey|string} userKey
+ * @param {number} createdAt - epoch 毫秒
+ * @returns {Promise<Object[]>}
+ */
+export function toOutboxRows(pushes: any[], userKey: CryptoKey | string, createdAt: number): Promise<any[]>;
+/**
+ * 把发出去的那部分标成 delivered（发送半途失败时只标已发出的段）。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {string[]} args.messageIds
+ */
+export function markPushesDelivered({ db, userId, messageIds }: {
+    db: any;
+    userId: string;
+    messageIds: string[];
+}): Promise<void>;
+/**
+ * 把这一批 push 里「没发出去的那些」从 outbox 撤掉。
+ *
+ * 取消撞上投递时用：整批 push 在开发之前就落进了 outbox，取消只拦住了 Web
+ * Push 这一路，剩下的行不撤掉，客户端下一次 GET /outbox 会照样把它们拉回去
+ * ——用户看到的就是「取消接口回了成功，消息还是来了」。
+ *
+ * 「哪些算没发出去」这条判据收在这里：投递侧只要把整批 push 和已发出的
+ * messageId 交过来就行。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {Array<{ messageId: string }>} args.pushes - 落进 outbox 的整批 push
+ * @param {string[]} args.sentIds - 已经发出去的 messageId
+ */
+export function discardUndeliveredPushes({ db, userId, pushes, sentIds }: {
+    db: any;
+    userId: string;
+    pushes: Array<{
+        messageId: string;
+    }>;
+    sentIds: string[];
+}): Promise<void>;
+/**
+ * 把某条任务名下「还没发出去的」行从 outbox 撤掉。
+ *
+ * 用在取消 / 顶替之后的每条收尾路上（`DELETE /message`、`supersedesUuid`、
+ * fire 内的 cancelTask、投递侧发现行已被取消）：任务此前投递到一半失败过的话，
+ * 没发出去的那几段还躺在 outbox 里等重试，任务行删掉它们也不会跟着走。不撤的
+ * 话客户端下一次 `GET /outbox` 照样把它们补收回去——用户看到的就是「取消接口回
+ * 了成功，消息还是来了」。
+ *
+ * 判据与 discardUndeliveredPushes 一致：只撤 delivered_at 为 null 的行。已经推
+ * 给设备的那几条撤不回来，行留着让客户端照常 ack——取消的意思是「别再发后面
+ * 的」，不是「把已经收到的从收件箱里抹掉」。
+ *
+ * 优先走适配器的按任务删除（discardUndeliveredOutboxForTask）：一个来回，且不
+ * 受未 ack 积压量的影响。没有这个方法的适配器（宿主自带的旧实现）退回翻页扫
+ * 描——被取消任务的行通常是最新的，积压超过扫描上限时正好扫不到它们，所以扫到
+ * 上限还没扫完必须吵出来，不能装作清干净了。
+ *
+ * 同样是 best-effort：适配器缺读/删任一侧就静默跳过，出错只记日志。取消 / 顶
+ * 替本身已经生效了，不该因为账本没清干净被翻成失败。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {string} args.taskUuid - 被取消 / 被顶替的任务 uuid
+ */
+export function discardUndeliveredPushesForTask({ db, userId, taskUuid }: {
+    db: any;
+    userId: string;
+    taskUuid: string;
+}): Promise<void>;
+/**
+ * @typedef {Object} CommittedBatchEntry
+ * @property {Object}  push      - 落进 outbox 的那条 push（解密后，与当初要发的是同一份）
+ * @property {boolean} delivered - Web Push 已经发出去过（delivered_at 不为空）
+ * @property {boolean} acked     - 客户端已经确认收到（acked_at 不为空）
+ */
+/**
+ * 找这次触发已经落进 outbox 的那一批 push。
+ *
+ * 认行的规矩（三条都要满足）：
+ *   - 行上 `total_messages` 不为空。推送链路定稿时每条都会写 messageIndex /
+ *     totalMessages（agentic 与冻结 prompt 两条路都是），`ctx.emitResult()` 落的
+ *     结果行没有；
+ *   - 解开之后 `taskUuid` / `occurrenceMs` 与本次触发对得上（这两个字段由库覆盖
+ *     写，宿主改不了，见 agentic-fire.js 的 stampTaskIdentity）；
+ *   - `messageKind` 不是 `result`（再挡一道：emitResult 的 payload 是宿主的形状，
+ *     万一自己带了 totalMessages 也不会被认成聊天分段）。
+ *
+ * 老链路的思考过程（reasoning）那条不带 totalMessages，不在认领范围内：批次落
+ * 定时它本来就只落收件箱、不推送，补推也轮不到它。
+ *
+ * 已经被客户端 ack 的行也要读回来：客户端在两次重试之间上线、把整批补收并 ack
+ * 了的话，这一批仍然算落定过——这时候要做的是「什么都不用推了」，而不是当成没
+ * 生成过、再生成一份新的。
+ *
+ * 读不到（适配器没有 outbox、查询抛错）→ null，调用方退回重新生成的老行为：查
+ * 不了不等于有，拿「可能多花一次」换「表结构没跟上的部署照样能重试送达」。
+ *
+ * @param {Object} args
+ * @param {Object} args.db
+ * @param {string} args.userId
+ * @param {CryptoKey|string} args.userKey
+ * @param {string|null|undefined} args.taskUuid
+ * @param {number|null} args.occurrenceMs - 本次触发的名义时刻
+ * @param {number} [args.now] - 当前时刻（epoch 毫秒，测试可注入）
+ * @returns {Promise<{ entries: CommittedBatchEntry[] } | null>} entries 按
+ *   messageIndex 升序；这次触发没有落定过批次 → null
+ */
+export function findCommittedBatch({ db, userId, userKey, taskUuid, occurrenceMs, now }: {
+    db: any;
+    userId: string;
+    userKey: CryptoKey | string;
+    taskUuid: string | null | undefined;
+    occurrenceMs: number | null;
+    now?: number;
+}): Promise<{
+    entries: CommittedBatchEntry[];
+} | null>;
+export type CommittedBatchEntry = {
+    /**
+     * - 落进 outbox 的那条 push（解密后，与当初要发的是同一份）
+     */
+    push: any;
+    /**
+     * - Web Push 已经发出去过（delivered_at 不为空）
+     */
+    delivered: boolean;
+    /**
+     * - 客户端已经确认收到（acked_at 不为空）
+     */
+    acked: boolean;
+};

package/dist/lib/push-policy.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 这条 push 要不要真的发出去。
+ *
+ * @param {Record<string, unknown>} push - 定稿后的 push 对象
+ * @param {Object}  options
+ * @param {boolean} options.outboxed - 这一批是否真的落进了 outbox
+ * @returns {boolean}
+ */
+export function shouldSendPush(push: Record<string, unknown>, { outboxed }: {
+    outboxed: boolean;
+}): boolean;

package/dist/lib/push-subscription-store.d.ts

@@ -0,0 +1,94 @@
+/** 适配器支不支持用户级订阅存储。 */
+export function supportsPushSubscriptionStore(db: any): boolean;
+/**
+ * 一个对象长得像不像 Web Push 订阅。只看投递必需的部分：没有 endpoint 就
+ * 谈不上往哪推。keys 缺失留给推送服务去拒，这里不替它判。
+ *
+ * @param {unknown} subscription
+ * @returns {boolean}
+ */
+export function isPushSubscriptionShape(subscription: unknown): boolean;
+/**
+ * 写入（覆盖）这个用户的订阅。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @param {Object} args.subscription - 明文订阅对象
+ * @param {number} [args.updatedAt] - epoch 毫秒，默认取当前时刻
+ * @returns {Promise<{ updatedAt: number }>}
+ */
+export function savePushSubscription({ db, userId, userKey, subscription, updatedAt }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+    subscription: any;
+    updatedAt?: number;
+}): Promise<{
+    updatedAt: number;
+}>;
+/**
+ * 把一行 push_subscriptions 解成明文订阅。行不在、或订阅列是空的 → null；
+ * 密文解不开（换过 masterKey 之类）、解出来不是 JSON → 抛。
+ *
+ * 单独拎出来是为了让调用方分得开两类失败：`db.getPushSubscription()` 抛出来
+ * 的是基础设施问题（表没建、读超时），换个时候重试有救；这里抛出来的是这一
+ * 行的密文废了，重试多少次都一样。两者压在同一个 try 里就只能一起处理，读不
+ * 到库会被当成「这个用户没登记过」。
+ *
+ * @param {{ subscription?: unknown, updated_at?: unknown }|null|undefined} row - `getPushSubscription()` 读回的行
+ * @param {string} userKey
+ * @returns {Promise<{ subscription: Object, updatedAt: number|null }|null>}
+ */
+export function decodePushSubscriptionRow(row: {
+    subscription?: unknown;
+    updated_at?: unknown;
+} | null | undefined, userKey: string): Promise<{
+    subscription: any;
+    updatedAt: number | null;
+} | null>;
+/**
+ * 读回这个用户的订阅（解密后的明文对象）。没有登记过 → null。
+ *
+ * 读库失败和解密失败都原样抛出去：投递链路上这两种都得让任务失败，分不分得
+ * 开无所谓；要分开处理的调用方（GET /push-subscription）自己走上面两步。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @returns {Promise<{ subscription: Object, updatedAt: number|null }|null>}
+ */
+export function loadPushSubscription({ db, userId, userKey }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+}): Promise<{
+    subscription: any;
+    updatedAt: number | null;
+} | null>;
+/**
+ * 投递前取订阅。取不到就抛——静默不发会让任务「成功」地什么都没做，用户
+ * 只看到消息凭空消失。抛出去走既有的重试 / 标记逻辑，原因也会记进 payload
+ * 的 lastError，`GET /messages` 上看得见。抛出的错误带稳定的 `code` 属性
+ * （'PUSH_SUBSCRIPTION_MISSING' / 'PUSH_SUBSCRIPTION_STORE_UNSUPPORTED'），
+ * 按类别分支请用它，别匹配 message 文案。
+ *
+ * `legacyFallback`：用户级存储里没有订阅时的兜底（升级前创建的任务把订阅
+ * 冻结在自己的 payload 里，这份订阅仍然有效）。存储里有订阅时永远用存储的
+ * 那份——它是用户最近一次登记的。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @param {unknown} [args.legacyFallback] - 旧任务 payload 里内嵌的订阅（可选）
+ * @returns {Promise<Object>} 明文订阅对象
+ */
+export function resolvePushSubscription({ db, userId, userKey, legacyFallback }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+    legacyFallback?: unknown;
+}): Promise<any>;

package/dist/lib/recurrence.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 这个字符串能不能当 IANA 时区 id 用。建任务 / 改任务时校验，运行时不再猜。
+ *
+ * @param {unknown} tzId
+ * @returns {boolean}
+ */
+export function isValidTimeZoneId(tzId: unknown): boolean;
+/**
+ * 从名义触发时刻往后推 `periods` 个周期。
+ *
+ * @param {number} occurrenceMs - 名义触发时刻（epoch 毫秒）
+ * @param {'daily'|'weekly'} recurrenceType
+ * @param {number} periods - 推几个周期（≥ 1）
+ * @param {string|null} [tzId] - IANA 时区 id；缺省按 UTC 推进
+ * @returns {number} 推进之后的时刻（epoch 毫秒）
+ */
+export function advanceOccurrence(occurrenceMs: number, recurrenceType: "daily" | "weekly", periods: number, tzId?: string | null): number;
+/**
+ * 从名义触发时刻往后推，找到第一个在 `nowMs` 之后的 occurrence，并顺带
+ * 报出中间跳过了哪些。
+ *
+ * 推进基准永远是名义时刻本身（不是「现在」），所以停摆多久都不会漂到别的
+ * 钟点上。
+ *
+ * @param {number} occurrenceMs
+ * @param {'daily'|'weekly'} recurrenceType
+ * @param {number} nowMs
+ * @param {string|null} [tzId]
+ * @returns {{ nextMs: number, skippedCount: number, skippedOccurrences: number[], skippedTruncated: boolean }}
+ *   `skippedCount` 含传进来的这一次（它自己就是没发出去的那一次）。
+ *   `skippedOccurrences` 最多列 {@link MAX_LISTED_SKIPPED_OCCURRENCES} 个，
+ *   超了只给首末两个并把 `skippedTruncated` 置 true。
+ */
+export function planNextOccurrence(occurrenceMs: number, recurrenceType: "daily" | "weekly", nowMs: number, tzId?: string | null): {
+    nextMs: number;
+    skippedCount: number;
+    skippedOccurrences: number[];
+    skippedTruncated: boolean;
+};
+/**
+ * 下一次触发时刻的 ISO 字符串（写库用）。
+ *
+ * @param {number} occurrenceMs
+ * @param {'daily'|'weekly'} recurrenceType
+ * @param {number} nowMs
+ * @param {string|null} [tzId]
+ * @returns {string}
+ */
+export function nextFutureOccurrence(occurrenceMs: number, recurrenceType: "daily" | "weekly", nowMs: number, tzId?: string | null): string;
+/** 快进时最多逐条列出多少个被跳过的名义时刻，超了只给首末两个。 */
+export const MAX_LISTED_SKIPPED_OCCURRENCES: 32;

package/dist/lib/request.d.ts

@@ -0,0 +1,182 @@
+/**
+ * 把请求正文读成字符串，`Content-Encoding: gzip` 的在这一步还原。
+ *
+ * 客户端把大 body（一次 fire_pack、一整批 client_state）压了再传能省下几倍
+ * 传输量，代价只有服务端这一次解压。所有带 body 的端点走同一个入口，谁都不用
+ * 各自判一遍这个头。
+ *
+ * 说是 gzip、字节却不是 gzip 开头时按明文处理：有些边缘网关会替你把请求体解
+ * 开却留着原来的 `Content-Encoding` 头，再解一次只会解出乱码。魔数判断两种情
+ * 况都接得住。
+ *
+ * 只认 gzip。deflate / br 回 415 而不是猜着解——猜错解出来的是一段乱码，会变
+ * 成一句让人找不着北的「请求体不是有效的 JSON」。
+ *
+ * @param {{ headers?: { get?: (name: string) => string|null }, text: () => Promise<string>, arrayBuffer: () => Promise<ArrayBuffer> }} request
+ *   Fetch API 的 Request（或形状相同的对象）。
+ * @param {{ maxBytes?: number }} [options] - `maxBytes`：解压后的字节上限，
+ *   默认 {@link DEFAULT_MAX_REQUEST_BODY_BYTES}。
+ * @returns {Promise<{ ok: true, body: string } | { ok: false, error: { status: number, body: Object } }>}
+ *   `error` 就是可以直接回给调用方的那个信封（与 handler 的返回同构）。
+ */
+export function readRequestBody(request: {
+    headers?: {
+        get?: (name: string) => string | null;
+    };
+    text: () => Promise<string>;
+    arrayBuffer: () => Promise<ArrayBuffer>;
+}, options?: {
+    maxBytes?: number;
+}): Promise<{
+    ok: true;
+    body: string;
+} | {
+    ok: false;
+    error: {
+        status: number;
+        body: any;
+    };
+}>;
+/**
+ * @typedef {{ code: string, message: string }} ValidationError
+ */
+/**
+ * @typedef {{
+ *   invalidJson?: ValidationError,
+ *   invalidType?: ValidationError
+ * }} ParseBodyOptions
+ */
+/**
+ * @typedef {{
+ *   ok: true,
+ *   data: Record<string, any>
+ * } | {
+ *   ok: false,
+ *   error: ValidationError
+ * }} ParseBodyResult
+ */
+/**
+ * Parse body into a JSON object.
+ *
+ * @param {unknown} body
+ * @param {ParseBodyOptions} [options]
+ * @returns {ParseBodyResult}
+ */
+export function parseBodyAsObject(body: unknown, options?: ParseBodyOptions): ParseBodyResult;
+/**
+ * Parse a standard JSON object body.
+ *
+ * @param {unknown} body
+ * @returns {ParseBodyResult}
+ */
+export function parseJsonBody(body: unknown): ParseBodyResult;
+/**
+ * Check if a value is a plain object (and not null/array).
+ *
+ * @param {unknown} value
+ * @returns {value is Record<string, any>}
+ */
+export function isPlainObject(value: unknown): value is Record<string, any>;
+/**
+ * Check if an object follows the encrypted payload envelope shape.
+ *
+ * @param {unknown} payload
+ * @returns {payload is { iv: string, authTag: string, encryptedData: string }}
+ */
+export function isEncryptedEnvelope(payload: unknown): payload is {
+    iv: string;
+    authTag: string;
+    encryptedData: string;
+};
+/**
+ * Parse and validate an encrypted payload envelope.
+ *
+ * @param {unknown} body
+ * @returns {ParseBodyResult}
+ */
+export function parseEncryptedBody(body: unknown): ParseBodyResult;
+/**
+ * 标准错误信封：{ status, body: { success: false, error: { code, message, details? } } }。
+ *
+ * @param {number} status
+ * @param {string} code
+ * @param {string} message
+ * @param {Object} [details]
+ */
+export function errorResponse(status: number, code: string, message: string, details?: any): {
+    status: number;
+    body: {
+        success: boolean;
+        error: {
+            code: string;
+            message: string;
+            details?: undefined;
+        } | {
+            code: string;
+            message: string;
+            details: any;
+        };
+    };
+};
+/**
+ * X-User-Id 门禁。所有按用户读写的端点共用这一份：规则（必填 + UUID v4）和
+ * 文案只此一处，改口径不用挨个 handler 找复制粘贴的副本。
+ *
+ * @param {Record<string, any>} headers
+ * @returns {{ userId: string, error?: undefined } | { error: ReturnType<typeof errorResponse> }}
+ */
+export function requireUserId(headers: Record<string, any>): {
+    userId: string;
+    error?: undefined;
+} | {
+    error: ReturnType<typeof errorResponse>;
+};
+/**
+ * Read a header value case-insensitively.
+ *
+ * @param {Record<string, any>} headers
+ * @param {string} name
+ * @returns {string}
+ */
+export function getHeader(headers: Record<string, any>, name: string): string;
+export namespace REQUEST_ERRORS {
+    namespace INVALID_JSON {
+        let code: string;
+        let message: string;
+    }
+    namespace INVALID_REQUEST_BODY {
+        let code_1: string;
+        export { code_1 as code };
+        let message_1: string;
+        export { message_1 as message };
+    }
+    namespace INVALID_ENCRYPTED_PAYLOAD {
+        let code_2: string;
+        export { code_2 as code };
+        let message_2: string;
+        export { message_2 as message };
+    }
+}
+/**
+ * 解压后请求体的字节上限（默认 32MB）。
+ *
+ * 只管 gzip 那条路：压缩数据能用很小的体积展开成极大的正文（几百 KB 换几个
+ * GB），不设上限等于把内存交给调用方决定。不压缩的请求体不受这个数约束，行为
+ * 与以前一致——那条路的体积本来就摆在传输量上，平台自己的请求大小限制盖得住。
+ */
+export const DEFAULT_MAX_REQUEST_BODY_BYTES: number;
+export type ValidationError = {
+    code: string;
+    message: string;
+};
+export type ParseBodyOptions = {
+    invalidJson?: ValidationError;
+    invalidType?: ValidationError;
+};
+export type ParseBodyResult = {
+    ok: true;
+    data: Record<string, any>;
+} | {
+    ok: false;
+    error: ValidationError;
+};

package/dist/lib/result-emitter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @typedef {Object} ResultEmitter
+ * @property {(payload: Object) => Promise<{ messageId: string, pushed: boolean }>} emitResult
+ *   把一条结果落进收件箱并推送出去。`payload` 是宿主自己的形状，只有两个约束：
+ *   必须是普通对象，且带一个非空的 `resultKind`（这类结果的名字，客户端按它
+ *   分流）。返回 `messageId`（补收和去重的键）与 `pushed`（这次推送有没有真
+ *   的发出去；`false` 只表示没能当场送达，行还在收件箱里等补收）。
+ */
+/**
+ * 造一份作用于某条任务的结果出口。
+ *
+ * 身份字段（`taskId` / `taskUuid` / `recurrenceType` / `occurrenceMs` /
+ * `messageKind`）由库覆盖写：它们描述的是这条任务行的事实，不是内容。
+ * `messageId` / `sessionId` / `timestamp` 宿主没给才补——`messageId` 的缺省
+ * 值掺了任务 id 与本次名义触发时刻，同一次触发重试时组出同一个 id，收件箱靠
+ * `(user_id, message_id)` 唯一约束天然去重，不会补出第二条。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {Object} args.task - 数据库任务行
+ * @param {string} args.userKey - per-user 存储密钥
+ * @param {Object} args.decryptedPayload - 解密后的任务 payload（取 messageType / recurrenceType / 老任务里的订阅）
+ * @param {string} args.messageIdBase - messageId 的前缀（与推送链路同一份）
+ * @param {string} args.sessionId
+ * @param {number|null} args.occurrenceMs
+ * @param {{ sendNotification: Function }|null} args.webpush
+ * @param {() => number} [args.now] - 取当前时刻（测试可注入假时钟）
+ * @param {(() => boolean)|null} [args.isCancelled] - 「这条任务是否已在投递期间
+ *   被取消 / 顶替」（run-tick 的租约心跳信号）。推送那条路的取消检查在
+ *   webpush 那层（guardWebpushWithLease），但 `notification.show: false` 的结
+ *   果不发推送，只有这个显式读法能拦得住它——不给的话那条路上没有任何取消检
+ *   查点。
+ * @returns {ResultEmitter}
+ */
+export function createResultEmitter({ db, task, userKey, decryptedPayload, messageIdBase, sessionId, occurrenceMs, webpush, now, isCancelled, }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    task: any;
+    userKey: string;
+    decryptedPayload: any;
+    messageIdBase: string;
+    sessionId: string;
+    occurrenceMs: number | null;
+    webpush: {
+        sendNotification: Function;
+    } | null;
+    now?: () => number;
+    isCancelled?: (() => boolean) | null;
+}): ResultEmitter;
+export type ResultEmitter = {
+    /**
+     *   把一条结果落进收件箱并推送出去。`payload` 是宿主自己的形状，只有两个约束：
+     *   必须是普通对象，且带一个非空的 `resultKind`（这类结果的名字，客户端按它
+     *   分流）。返回 `messageId`（补收和去重的键）与 `pushed`（这次推送有没有真
+     *   的发出去；`false` 只表示没能当场送达，行还在收件箱里等补收）。
+     */
+    emitResult: (payload: any) => Promise<{
+        messageId: string;
+        pushed: boolean;
+    }>;
+};

package/dist/lib/retry-policy.d.ts

@@ -0,0 +1,11 @@
+export function resolveMaxDeliveryRetries(ctx: any): any;
+/** Resolve once per attempt, before any generation hook or model request. */
+export function resolveMaxGenerationRetries(ctx: any, safeTask: any): any;
+/** Shared by fire receipts and both delivery entry points; never alters errors. */
+export function failureRetryDecision(state: any, error: any): {
+    failureStage: string;
+    retryLimit: any;
+    willRetry: boolean;
+};
+/** Number of retries after the first attempt when no policy is configured. */
+export const DEFAULT_MAX_DELIVERY_RETRIES: 3;