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

package/dist/lib/encryption.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Derive a user-specific encryption key from the master key.
+ *
+ * @param {string} userId    - Unique user identifier.
+ * @param {string} masterKey - 64-char hex master key.
+ * @returns {Promise<string>} 64-char hex key.
+ */
+export function deriveUserEncryptionKey(userId: string, masterKey: string): Promise<string>;
+/**
+ * Decrypt a client-encrypted request body (AES-256-GCM, base64 encoded).
+ *
+ * @param {{ iv: string, authTag: string, encryptedData: string }} encryptedPayload
+ * @param {string} encryptionKey - 64-char hex key.
+ * @returns {Promise<Object>} Decrypted JSON object.
+ */
+export function decryptPayload(encryptedPayload: {
+    iv: string;
+    authTag: string;
+    encryptedData: string;
+}, encryptionKey: string): Promise<any>;
+/**
+ * Encrypt a JSON payload for API transfer (AES-256-GCM, base64 encoded).
+ *
+ * @param {string|Object} payload
+ * @param {string} encryptionKey - 64-char hex key.
+ * @returns {Promise<{ iv: string, authTag: string, encryptedData: string }>}
+ */
+export function encryptPayload(payload: string | any, encryptionKey: string): Promise<{
+    iv: string;
+    authTag: string;
+    encryptedData: string;
+}>;
+/**
+ * Encrypt data for database storage (hex encoded, colon-separated).
+ *
+ * @param {string} text          - Plaintext string.
+ * @param {string} encryptionKey - 64-char hex key.
+ * @returns {Promise<string>} Format: iv:authTag:encryptedData
+ */
+export function encryptForStorage(text: string, encryptionKey: string): Promise<string>;
+/**
+ * Decrypt data from database storage format.
+ *
+ * @param {string} encryptedText - Format: iv:authTag:encryptedData
+ * @param {string} encryptionKey - 64-char hex key.
+ * @returns {Promise<string>} Plaintext string.
+ */
+export function decryptFromStorage(encryptedText: string, encryptionKey: string): Promise<string>;

package/dist/lib/errors.d.ts

@@ -0,0 +1,273 @@
+/**
+ * 这个错误是不是「重试也好不了」。认 NonRetryableError，也认任何自带
+ * `permanent: true` 的错误对象（跨包/跨版本安全）。
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isNonRetryableError(error: unknown): boolean;
+/**
+ * 把一个已经构造好的错误标成确定性失败（就地改，原样返回），顺带补一个稳定
+ * 的 `code`（错误自己带了 code 就不覆盖）。
+ *
+ * 用在错误由别处构造、又想保住它原本类型的时候——比如契约校验抛的
+ * `TypeError`：宿主按 `instanceof TypeError` 分流的代码不该因为库多标了一个
+ * 字段就走岔。自己现造错误的地方直接用 {@link NonRetryableError} 更直白。
+ *
+ * @template T
+ * @param {T} error
+ * @param {string} [code]
+ * @returns {T}
+ */
+export function markPermanent<T>(error: T, code?: string): T;
+/**
+ * 这个错误是不是「投递期间任务被取消/顶替」。
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isTaskCancelledError(error: unknown): boolean;
+/**
+ * 推送半途失败、而这一批**没有**落进 outbox 时，这次失败还能不能重试（就地标
+ * 注，原样返回传入的错误）。
+ *
+ * 落进了 outbox 的批次重试时只补推送、不重新生成（见 lib/message-processor.js
+ * 的 redeliverCommittedBatch）。没落进去的（适配器没有 outbox，或者这一批落行
+ * 失败）没有这条退路：重试只能把整条内容重新生成一遍。那样做安不安全，看设备上
+ * 已经有没有这次触发的东西：
+ *
+ *   - 一条都没推出去 → 客户端什么都没收到，重新生成的那一份就是它唯一见到的一
+ *     份。照旧重试（会多花一次生成——没有收件箱兜着的时候，这是唯一能把消息送
+ *     到的办法）；
+ *   - 已经推出去了几条 → 重新生成的内容跟设备上那几条不是同一份，客户端会看到
+ *     前半截来自第一次生成、后半截来自第二次。所以就地判终审（标 permanent）：
+ *     一次性任务标 failed、循环任务作废本次 occurrence，没推出去的那几段就此
+ *     放弃。
+ *
+ * 取消（TASK_CANCELLED）不归这里管，照旧按取消收尾。
+ *
+ * @template T
+ * @param {T} error - 推送那一步抛的错误
+ * @param {{ outboxed: boolean, pushedCount: number }} state - 这一批落没落进
+ *   outbox、已经推出去了几条
+ * @returns {T}
+ */
+export function markUnrecoverablePartialDelivery<T>(error: T, { outboxed, pushedCount }: {
+    outboxed: boolean;
+    pushedCount: number;
+}): T;
+/**
+ * 这个错误是不是「LLM 上游明确拒了这次请求、重试也不会好」。判据见
+ * {@link PERMANENT_LLM_STATUSES}。
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isPermanentLlmFailure(error: unknown): boolean;
+/**
+ * 按 {@link isPermanentLlmFailure} 的口径就地给 LLM 错误标上 `permanent: true`
+ * （原样返回传入的错误）。
+ *
+ * 标在错误对象上而不是只在投递侧判：fire-time hook（`onFireSettled` /
+ * `onAfterSend`）拿到的就是这个对象，宿主用 `error.permanent === true` 判断
+ * 「这是终态、该告诉用户了」。只在投递侧判的话，hook 看到的是一个没有
+ * `permanent` 的错误，任务却已经被判死了。
+ *
+ * 唯一的调用点是 lib/llm.js 的 callLlm（server 侧所有 LLM 调用都走它），别在
+ * 别处各自判。
+ *
+ * @template T
+ * @param {T} error
+ * @returns {T}
+ */
+export function markPermanentIfLlmRejected<T>(error: T): T;
+/**
+ * 这次投递失败要不要判成永久性的（不再重试）。五个来源：
+ *   - 已知的永久性错误码（见 {@link PERMANENT_ERROR_CODES}）；
+ *   - hook 侧抛出的 NonRetryableError（`permanent`，见 {@link NonRetryableError}）——
+ *     fire_pack 缺失、解析失败这类重试必然同败的错，隔两分钟再试三次只是让用户
+ *     多白等十二分钟，还把情绪评估之类的计费重跑三遍；
+ *   - LLM 上游明确拒了这次请求（401 / 403 / 400 …，见
+ *     {@link PERMANENT_LLM_STATUSES}）。这一条同样经由 `permanent` 传进来：错
+ *     误在 lib/llm.js 抛出的那一刻就标好了（见 {@link markPermanentIfLlmRejected}），
+ *     hook 看到的和这里判的是同一个结论；
+ *   - 推送服务判了这条订阅的死刑（见 {@link TERMINAL_PUSH_STATUSES}）；
+ *   - 推送服务说这条 payload 太大（见 {@link PUSH_PAYLOAD_TOO_LARGE_STATUS}）。
+ *
+ * @param {{ permanent?: unknown, errorCode?: unknown, pushStatus?: unknown }} failure
+ * @returns {boolean}
+ */
+export function isPermanentDeliveryFailure(failure: {
+    permanent?: unknown;
+    errorCode?: unknown;
+    pushStatus?: unknown;
+}): boolean;
+/**
+ * 发一条 push，失败时自动标上「这是发 push 那一步抛的」。
+ *
+ * 发 push 的地方一律走这里，别各自写 `try { send } catch { throw
+ * tagPushStatusCode(e) }`：漏标一处，那条路上的 410 就读不出状态码，一条早就
+ * 失效的订阅会被当成普通失败，在退避阶梯上把 LLM 重跑三轮。忘了标是没有任何
+ * 提示的。
+ *
+ * @param {{ sendNotification: (subscription: any, payload: string) => Promise<any> }} webpush
+ * @param {any} subscription
+ * @param {string} payloadJson
+ * @returns {Promise<any>}
+ */
+export function sendTaggedPush(webpush: {
+    sendNotification: (subscription: any, payload: string) => Promise<any>;
+}, subscription: any, payloadJson: string): Promise<any>;
+/**
+ * 读推送服务回的状态码。没被 {@link tagPushStatusCode} 标过 → null。
+ *
+ * @param {unknown} error
+ * @returns {number|null}
+ */
+export function readPushStatusCode(error: unknown): number | null;
+/**
+ * lastError 里的机读标注：`errorCode` 是底层错误的稳定 code（如
+ * `PUSH_PAYLOAD_TOO_LARGE`），`pushStatus` 是推送服务回的 HTTP 状态码。两个都
+ * 没有 → undefined，不往记录里塞空字段。
+ *
+ * reason 那句是给用户看的人话、措辞随时会变，判断「该让用户重建订阅还是裁短
+ * 内容」得读这两个字段。定时任务（run-tick）与 instant 任务
+ * （processMessagesByUuid）共用这一份，两条路记下来的形状一致。
+ *
+ * code 是标识符不是人话，不用脱敏，但也别让一个来路不明的超长 code 撑大明文
+ * 列——截到 64 字符，够放所有约定过的码。
+ *
+ * @param {string|null|undefined} errorCode
+ * @param {number|null|undefined} pushStatus
+ * @returns {{ errorCode?: string, pushStatus?: number }|undefined}
+ */
+export function buildErrorExtra(errorCode: string | null | undefined, pushStatus: number | null | undefined): {
+    errorCode?: string;
+    pushStatus?: number;
+} | undefined;
+/**
+ * 把错误原因脱敏成能明文落库（任务行 last_error 列）的摘要。
+ *
+ * 任务内容一律密文落库，last_error 是唯一一列明文的「为什么没发出去」——
+ * 错误消息偶尔会回显请求细节（上游 API 的报错带 URL、header 片段），所以
+ * 长得像凭据的 token 一律遮掉，再截断。
+ *
+ * 遮什么、怎么遮由 @rei-standard/amsg-shared 的 `redactCredentials` 说了算，
+ * 这里只负责压平空白和截断。
+ *
+ * @param {unknown} reason
+ * @returns {string}
+ */
+export function sanitizeErrorSummary(reason: unknown): string;
+/**
+ * @typedef {Object} ErrorCause
+ * @property {'config'|'request'|'tick'} stage - 在哪一段炸的
+ * @property {string} name - 错误类型（`error.name`，认不出来时是 'Error'）
+ * @property {string} [message] - 脱敏后的错误消息。降级 500（配置都没建起来那条
+ *   路）回给跨域调用方时不带这个字段——那条路的 CORS 头是回显来访 Origin 的，任
+ *   意第三方页面都能读，而构建期异常原文里常有 binding 名、内网域名、环境变量
+ *   名。同源 / 无 Origin 的请求照旧带全文，`wrangler tail` 里也一直有。
+ * @property {string} [code] - 错误自带的 `code` 字符串（有才带）
+ */
+/**
+ * 把一个异常整理成能随响应体一起回给调用方的机读原因。
+ *
+ * 500 只回一句「服务器内部错误」的话，真因（`D1_ERROR: no such table:
+ * message_outbox`、存储层写超时……）就只剩 console.error 里那一行，调用方拿不
+ * 到，用户看到的也只是「服务器内部错误」——不知道哪儿坏了，也不知道该点哪里。
+ * 这个函数把异常压成几个固定字段，让调用方能机读、能展示。
+ *
+ * 只带错误类型和消息文本。消息先过 `sanitizeErrorSummary`（遮掉长得像凭据的
+ * 串、截断到 500 字符）；密钥、用户数据、任务正文都不在 `error.message` 上，
+ * 也不往这里放。
+ *
+ * @param {unknown} error - 捕获到的异常，也收 `{ name, message }` 这样的普通对象
+ * @param {'config'|'request'|'tick'} stage - 'config' = 构建配置时抛的（少了
+ *   binding / 环境变量）；'request' = 路由或处理器抛的；'tick' = cron 那一跳抛的
+ * @returns {ErrorCause}
+ */
+export function summarizeErrorCause(error: unknown, stage: "config" | "request" | "tick"): ErrorCause;
+/**
+ * 确定性失败——重试必然同败，别再排退避阶梯。
+ *
+ * 典型场景全在 fire-time hook 里：onBeforeFire 发现 fire_pack 缺失、解析失
+ * 败、缺必要的段……这类错误不会因为过两分钟再跑一次就好，按普通投递失败重
+ * 试三轮只是让用户多白等十几分钟，还把 hook 里的计费调用（情绪评估之类）
+ * 重复烧三遍。hook 抛这个类（或任何带 `permanent: true` 的错误），run-tick
+ * 收到后跳过退避：一次性任务直接标 failed（原因进 last_error / payload 的
+ * lastError），循环任务直接作废本次 occurrence。
+ *
+ * `code`（可选）会透传到 processSingleMessage 的 errorCode，宿主想按错误类
+ * 别分流时用它。
+ *
+ * 用 `permanent` 属性而不是 instanceof 做判定：宿主的 worker 里可能打包了另
+ * 一份本库（版本错开、bundler 双实例），跨 realm 的 instanceof 靠不住。
+ */
+export class NonRetryableError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ code?: string, cause?: unknown }} [options]
+     */
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+    permanent: boolean;
+    code: string;
+}
+/**
+ * 部署级的配置 / 适配器能力错误——坏的不是这条任务，是这个部署。
+ *
+ * 典型场景：`hooks.onBeforeFire` 配了但 `onLLMOutput` 忘了配、`executeToolCalls`
+ * 没配、自定义适配器缺 `createTask` / `deleteTaskByUuid` / `upsertClientState`。
+ * 这类错误重试确实好不了，但**不能**判终态：同一个坏部署下每条到点的任务都会
+ * 撞同一个错，判终态就等于在那段时间里把每一条一次性任务都永久标 `failed`，
+ * 运维改好配置重新部署也捞不回来了（行已不在 pending，`PUT /update-message`
+ * 回 409）。所以留在退避阶梯上——配置一修好，还在阶梯上的任务下一跳就正常发
+ * 出去。这跟 VAPID 配错回的 400/401/403 是同一个道理，见
+ * {@link PUSH_PAYLOAD_TOO_LARGE_STATUS} 那段注释。
+ *
+ * 带 `code` 但不带 `permanent`：失败原因照旧进 last_error 的 `errorCode`，宿主
+ * 想分流照样读得到，只是不再跳过重试。
+ */
+export class DeploymentConfigError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ code?: string, cause?: unknown }} [options]
+     */
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+    code: string;
+}
+/**
+ * 投递期间发现「这条任务已经不归本次投递管了」时，推送侧抛的错误码：行被
+ * `DELETE /message` 取消、被 `supersedesUuid` 顶替，或被别的执行者收尾了。
+ *
+ * 发送方（message-processor 的正文投递、agentic-fire 的 hook 投递）靠它区分
+ * 「取消」和「发失败」——两者的收尾完全不同：取消要把这一批还没发出去的
+ * outbox 行撤掉，发失败则要把它们留着等补收。
+ */
+export const TASK_CANCELLED_CODE: "TASK_CANCELLED";
+export type ErrorCause = {
+    /**
+     * - 在哪一段炸的
+     */
+    stage: "config" | "request" | "tick";
+    /**
+     * - 错误类型（`error.name`，认不出来时是 'Error'）
+     */
+    name: string;
+    /**
+     * - 脱敏后的错误消息。降级 500（配置都没建起来那条
+     * 路）回给跨域调用方时不带这个字段——那条路的 CORS 头是回显来访 Origin 的，任
+     * 意第三方页面都能读，而构建期异常原文里常有 binding 名、内网域名、环境变量
+     * 名。同源 / 无 Origin 的请求照旧带全文，`wrangler tail` 里也一直有。
+     */
+    message?: string;
+    /**
+     * - 错误自带的 `code` 字符串（有才带）
+     */
+    code?: string;
+};

package/dist/lib/llm-credentials-store.d.ts

@@ -0,0 +1,147 @@
+/** 适配器支不支持用户级凭据存储。 */
+export function supportsLlmCredentialsStore(db: any): boolean;
+/**
+ * 一个字符串是不是合法 cred_id：非空、≤128 字符、不含控制字符。
+ *
+ * @param {unknown} credId
+ * @returns {boolean}
+ */
+export function isValidCredId(credId: unknown): boolean;
+/**
+ * 一份凭据 value 的形状：{ apiUrl, apiKey, primaryModel } 三字段全必填。
+ * 校验口径对齐 update-message 的凭据刷新：只查 truthy（+ 长度上限），不做
+ * 格式校验。
+ *
+ * @param {unknown} value
+ * @returns {string|null} 错误描述，合法时 null
+ */
+export function validateCredValue(value: unknown): string | null;
+/**
+ * 任务 payload 里 credRefs 字段的形状校验（schedule-message 与 update-message
+ * 共用一份口径）。
+ *
+ * @param {unknown} credRefs
+ * @returns {string|null} 错误描述，合法时 null
+ */
+export function validateCredRefs(credRefs: unknown): string | null;
+/**
+ * payload 带没带可用的 chat 凭据引用（`credRefs.chat`）。fire 侧的
+ * taskNeedsLlm 和校验共用这一个判据。
+ *
+ * @param {Object|null|undefined} payload
+ * @returns {boolean}
+ */
+export function hasChatCredRef(payload: any | null | undefined): boolean;
+/**
+ * payload 带没带非空的 credRefs 映射（不管里面是什么 purpose）。自排继承要在
+ * 「有 chat 引用」和「只有非 chat 引用」之间分支，这是后者用的那半个判据。
+ *
+ * @param {Object|null|undefined} payload
+ * @returns {boolean}
+ */
+export function hasCredRefs(payload: any | null | undefined): boolean;
+/**
+ * 批量写入（覆盖）这个用户的凭据。value 在这里加密。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @param {Array<{ credId: string, value: Object }>} args.credentials
+ * @returns {Promise<{ upserted: number }>}
+ */
+export function saveLlmCredentials({ db, userId, userKey, credentials }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+    credentials: Array<{
+        credId: string;
+        value: any;
+    }>;
+}): Promise<{
+    upserted: number;
+}>;
+/**
+ * 排程 / 更新时的存在性检查：credRefs 里引用的 credId 有哪些还不在表里。
+ * 空缺不是这里的错误——回给调用方点名，由它组 4xx。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {Object} args.credRefs
+ * @returns {Promise<string[]>} 缺失的 credId（去重）
+ */
+export function findMissingCredIds({ db, userId, credRefs }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    credRefs: any;
+}): Promise<string[]>;
+/**
+ * 按 cred_id 解出一份明文凭据。每次调用返回**新对象**；没有这行 / 解不开
+ * （换过 masterKey）→ null。
+ *
+ * 结果只该被「拿到就用」：合进发给 LLM 的请求对象、或在 hook 里当场发请求。
+ * 不要写回 payload / ctx / metadata——那些对象会流向 hook 和 push，凭据跟着
+ * 走就把 CREDENTIAL_PAYLOAD_KEYS 那道防线绕空了。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @param {string} args.credId
+ * @returns {Promise<{ apiUrl: string, apiKey: string, primaryModel: string }|null>}
+ */
+export function resolveLlmCredential({ db, userId, userKey, credId }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+    credId: string;
+}): Promise<{
+    apiUrl: string;
+    apiKey: string;
+    primaryModel: string;
+} | null>;
+/**
+ * fire 时的 chat 凭据解析（message-processor 的两条老路径和 agentic 循环共用）。
+ *
+ * 解析顺序：
+ *   1. payload 没带 `credRefs.chat` → 返回 null，调用方按内联三件套的老行为走
+ *      （存量任务的零开销路径，不多打一次库）。
+ *   2. 带了 → 查表取值，查到就用表里那份（表是用户最近一次登记的，比冻结在
+ *      行里的新）。
+ *   3. 查不到行（被删 / 换过 masterKey / 适配器不支持）→ 退回内联三件套兜底
+ *      （update-message 给存量任务补 credRefs 时内联还留着，正是给这里用的）。
+ *   4. 都没有 → 抛 `code: 'CREDENTIAL_MISSING'`，走任务的常规失败/重试——用户
+ *      补传凭据后下一轮自愈。
+ *
+ * 返回的对象只许合进**发给 LLM 的请求对象**，见 resolveLlmCredential 的红线。
+ *
+ * @param {Object} args
+ * @param {import('../adapters/interface.js').DbAdapter} args.db
+ * @param {string} args.userId
+ * @param {string} args.userKey
+ * @param {Object} args.decryptedPayload
+ * @returns {Promise<{ apiUrl: string, apiKey: string, primaryModel: string }|null>}
+ */
+export function resolveFireCredentials({ db, userId, userKey, decryptedPayload }: {
+    db: import("../adapters/interface.js").DbAdapter;
+    userId: string;
+    userKey: string;
+    decryptedPayload: any;
+}): Promise<{
+    apiUrl: string;
+    apiKey: string;
+    primaryModel: string;
+} | null>;
+/** cred_id 的长度上限。 */
+export const CRED_ID_MAX_LENGTH: 128;
+/** value 单字段（apiUrl / apiKey / primaryModel）的长度上限。 */
+export const CRED_VALUE_FIELD_MAX_LENGTH: 2048;
+/** PUT 单批最多几条。 */
+export const CRED_PUT_BATCH_MAX: 100;
+/** 单用户最多存几行凭据。 */
+export const CRED_ROWS_PER_USER_MAX: 500;
+/** credRefs 最多几个 purpose 条目。 */
+export const CRED_REFS_MAX_ENTRIES: 16;
+/** credRefs 的 purpose 键长度上限。 */
+export const CRED_REFS_KEY_MAX_LENGTH: 64;

package/dist/lib/llm.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 与 shared 的 callLlm 同签名、同返回值；失败时抛出的错误若是「上游拒了、重试
+ * 也不会好」的那一类，会多带 `permanent: true`。
+ *
+ * @param {Object} payload
+ * @param {Object} [options]
+ * @returns {Promise<{ response: unknown, content: string }>}
+ */
+export function callLlm(payload: any, options?: any): Promise<{
+    response: unknown;
+    content: string;
+}>;

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

@@ -0,0 +1,82 @@
+/**
+ * Process a single database task row: decrypt → generate content → push.
+ *
+ * 每次投递都先看这次触发的整批是不是已经落进了 outbox：落进去了就只补推送、
+ * 不再生成（见 redeliverCommittedBatch），返回值带 `redelivered: true`。
+ *
+ * @param {import('../adapters/interface.js').TaskRow} task
+ * @param {ProcessorContext} ctx
+ * @param {string} [providedMasterKey]
+ * @param {{ userKey: string, payload: Object } | null} [predecrypted] - 调用方
+ *   （run-tick 的预扫描）已经解好的 payload；传了就不再解第二遍。
+ * @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;
+    payload: any;
+} | null): 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;
+}>;
+/**
+ * Process a single message identified by UUID (used for instant type).
+ *
+ * @param {string} uuid
+ * @param {ProcessorContext} ctx
+ * @param {number} [maxRetries=2]
+ * @param {string} [userId]
+ * @param {string} [providedMasterKey]
+ * @returns {Promise<{ success: boolean, messagesSent?: number, retriesUsed?: number, reasoningError?: string, error?: Object }>}
+ *   `reasoningError` 只在正文都发出去了、思考过程那一条没发成时出现（思考过程是
+ *   附赠内容，它发不出去不算这条消息失败）。调用方拿它提示用户这次没有思考过程，
+ *   不带这个字段就是整轮都送到了。
+ *
+ *   这条路是请求里当场投递，不支持 onBeforeFire 的 `{ defer }`：返回它会得到
+ *   AGENTIC_DEFER_UNSUPPORTED 的配置错误，按这里的失败流程处理。
+ */
+export function processMessagesByUuid(uuid: string, ctx: ProcessorContext, maxRetries?: number, userId?: string, providedMasterKey?: string): Promise<{
+    success: boolean;
+    messagesSent?: number;
+    retriesUsed?: number;
+    reasoningError?: string;
+    error?: any;
+}>;
+export { normalizeAiApiUrl } from "./llm.js";
+export type ProcessorContext = {
+    maxDeliveryRetries?: number;
+    maxGenerationRetries?: number | ((task: any) => number | undefined);
+    /**
+     * - The web-push module instance (already VAPID-configured).
+     */
+    webpush: any;
+    /**
+     * - { email, publicKey, privateKey }
+     */
+    vapid: any;
+    db: import("../adapters/interface.js").DbAdapter;
+    /**
+     * 分片传输的限额，宿主传给 `installReiSW` 的那一份原样传过来即可（见
+     * resolveMultipartOptions）。不传 = 两边都用默认值。
+     */
+    multipart?: {
+        maxChunkBytes?: number;
+        maxChunks?: number;
+        maxTotalBytes?: number;
+        ttlMs?: number;
+    };
+};